mdkg 0.0.1 → 0.0.2

package/dist/init/core/rule-2-context-pack-rules.md

@@ -0,0 +1,186 @@
+---
+id: rule-2
+type: rule
+title: mdkg context pack rules (selection, ordering, verbose, checkpoints)
+tags: [agents, mdkg, pack, spec]
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: 2026-01-06
+updated: 2026-01-14
+---
+
+# mdkg context pack rules
+
+A **context pack** is a deterministic export that bundles the root node plus relevant linked nodes, ordered for agent execution and constraint compliance.
+
+Packs are the core feature that turns a Markdown graph into a repeatable “what to read before you code” artifact.
+
+## Goals
+
+- Deterministic: same repo state + same command → same pack ordering and contents.
+- Relevant: include the minimum set needed to execute the work well.
+- Safe: enforce limits to prevent runaway packs.
+- Flexible: export to Markdown / JSON / TOON / XML.
+
+## Command (conceptual)
+
+`mdkg pack <id-or-qid> [--depth N] [--verbose] [--edges ...] [--ws <alias>] [--format md|json|toon|xml] [--out <path>]`
+
+Notes:
+- CLI normalizes to lowercase before processing.
+- Packs are generated using the global index (auto-reindexed if stale).
+
+## Node selection
+
+### Root node
+The root node is always included.
+
+### Default depth
+Default traversal depth is `2` unless overridden.
+
+### Default edges
+By default, traversal includes:
+- `parent`
+- `epic`
+- `relates`
+
+Non-edge references and metadata fields like `refs`, `links`, and `artifacts` are searchable and included in pack exports, but they are NOT traversed by default unless their corresponding graph edge keys are selected.
+
+Optional edges (include only when requested via `--edges`):
+- `blocked_by`
+- `blocks`
+- `prev`
+- `next`
+
+`--edges` adds to the default edge set; duplicates are ignored.
+
+### Traversal method
+- BFS traversal from the root to the specified depth.
+- Nodes are de-duplicated by `qid` (qualified ID) in global mode.
+
+## Ordering rules
+
+Ordering is designed to maximize agent usefulness and rule compliance.
+
+### Task-root ordering (recommended default)
+
+1) Root `task-*` / `bug-*`
+2) Immediate context:
+   - `parent` (if present)
+   - `epic` (if present)
+   - related `chk-*` (checkpoint summaries) when present
+   - blockers/blocked-by nodes when they are immediate (depth=1) and included via `--edges`
+3) Architecture and constraints:
+   - `edd-*`
+   - `dec-*`
+   - `rule-*`
+4) Product requirements:
+   - `prd-*`
+5) Supporting docs:
+   - `prop-*` (and any future supporting types)
+6) Work graph neighbors (if included):
+   - blockers, blocks, prev/next chain, related tasks/bugs
+
+### Non-task root ordering (fallback)
+
+If the root is not a `task-*` or `bug-*`, the root is still first. Remaining nodes are ordered by type priority:
+
+1) `edd-*`
+2) `dec-*`
+3) `rule-*`
+4) `prd-*`
+5) `prop-*`
+6) `epic-*`
+7) `feat-*`
+8) `task-*`
+9) `bug-*`
+10) `chk-*`
+
+### Tie-breakers (stable determinism)
+
+Within each group:
+1) type priority (as listed above)
+2) numeric ID ascending (use the trailing number in `<prefix>-<number>` when present; otherwise treat as infinity)
+3) title lexicographic (final tie-break)
+
+## Verbose mode (`--verbose`)
+
+Verbose mode is intended for “fresh agent sessions” and MUST add baseline rules even if not directly linked.
+
+When `--verbose` is enabled:
+- include IDs listed in `.mdkg/core/core.md` (one per line)
+- pinned core inclusion MUST obey pack limits
+- IDs are resolved as `id` or `qid`; ambiguous matches should warn and be skipped unless a qualified ID is provided
+
+If a pinned core ID does not exist, pack generation should warn but continue.
+
+## Checkpoints (compression nodes)
+
+Checkpoints (`chk-*`) are phase summaries that reduce context sprawl.
+
+### Recommended checkpoint frontmatter fields
+- `scope: [id, id, ...]` (IDs covered by the checkpoint)
+
+### Pack behavior with checkpoints
+- If the root node relates to a checkpoint, include the checkpoint early (immediate context).
+- Optional future behavior (not required for v1): `--prefer-checkpoints`
+  - when enabled, if many “done” nodes are in scope and a checkpoint covers them, include the checkpoint instead of the underlying nodes (while still including core constraints like rules/decisions as needed).
+
+## Limits
+
+Default limits (configurable):
+- `max_nodes: 25`
+- `max_bytes: 2,000,000` for Markdown output
+
+When a limit is hit:
+- the root node MUST remain included
+- higher-priority types (`edd/dec/rule/prd`) should be favored over low-priority neighbors
+- pack metadata must record that truncation occurred
+- `max_bytes` is enforced for Markdown output; other formats ignore byte limits in v1
+
+## Export formats
+
+### Markdown (`--format md`)
+Markdown packs MUST include:
+- a pack header with metadata (root, depth, verbose, node count, truncation flags)
+- an ordered “included nodes” list
+- each node content separated by a stable divider
+- node headers should include: `qid`, `type`, `title`, `status` (if any), `priority` (if any), `path`, and the searchable frontmatter lists `links` and `artifacts`
+
+Node bodies should exclude the full raw frontmatter by default to reduce noise, but the header MUST surface key searchable fields (at minimum: `links` and `artifacts`, plus `refs` when present). A future flag like `--include-frontmatter` may include the full raw frontmatter.
+
+### JSON (`--format json`)
+JSON packs MUST include:
+- `meta` (root, generation timestamp, depth, verbose, truncation info)
+- `nodes` array in the same order as Markdown packs
+- each node includes:
+  - `qid`, `id`, `workspace`, `type`, `title`, `status`, `priority` (if any), `path`
+  - `frontmatter` (parsed restricted subset, including `links`, `artifacts`, `refs`, and `aliases` when present)
+  - `body` (content excluding frontmatter)
+
+### TOON (`--format toon`)
+TOON packs SHOULD mirror JSON semantics:
+- meta
+- ordered nodes
+- node fields as above
+
+Exact TOON encoding is defined by the project’s TOON spec adoption.
+
+### XML (`--format xml`)
+XML packs SHOULD mirror JSON semantics:
+- `<pack>` root element with `<meta>` and `<nodes>`
+- `<nodes>` contains ordered `<node>` elements
+- node fields align with JSON exporter
+- list fields are represented as repeated child elements
+- body content must be safely encoded
+
+## Determinism requirements
+
+Given the same repo state and command flags:
+- included node set must be identical
+- ordering must be identical
+- only timestamps in metadata may differ between runs

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

@@ -0,0 +1,177 @@
+---
+id: rule-3
+type: rule
+title: mdkg cli contract (root-only, commands, flags, exit codes)
+tags: [cli, contract, mdkg, spec]
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: 2026-01-06
+updated: 2026-01-22
+---
+
+# mdkg CLI contract
+
+This rule defines the **stable CLI behavior** for mdkg v1. The CLI is designed for humans and AI coding agents to use deterministically.
+
+## Root-only requirement
+
+mdkg commands are intended to run at the **repo root**.
+
+- The repo root is the current working directory containing `./.mdkg/config.json`.
+- mdkg MUST NOT walk upward to find config by default.
+- If config is not found in the current directory:
+  - mdkg MUST exit non-zero and print a helpful error.
+  - Users may pass `--root <path>` to run from elsewhere.
+
+### `--root`
+`--root <path>` sets the root directory explicitly.
+
+- `<path>` may be the repo root or a path that contains `.mdkg/config.json`.
+- When `--root` is set, mdkg behaves as if it was invoked from that root.
+
+## Case normalization
+
+- The CLI MUST accept any case for user inputs (types, IDs, flags values).
+- Before processing, mdkg MUST normalize:
+  - IDs to lowercase
+  - types to lowercase
+  - status to lowercase
+  - workspace aliases to lowercase
+  - template set names to lowercase
+
+## Cache / auto reindex (default)
+
+- Cache is enabled by default.
+- Commands that rely on the graph MUST:
+  1) load `.mdkg/config.json`
+  2) check if the global index is stale
+  3) auto-reindex if stale (unless `--no-reindex` or config disables)
+  4) proceed using the global index
+
+### Flags
+- `--no-cache` (optional): bypass reading the cache (debug only)
+- `--no-reindex` (optional): do not auto rebuild when stale (CI/debug)
+
+In v1, `--no-cache` and `--no-reindex` are intended as escape hatches, not the normal workflow.
+
+## Workspace behavior
+
+Workspaces are registered in `.mdkg/config.json`.
+
+- Default behavior is **global** across all registered workspaces.
+- Many commands SHOULD support:
+  - `--ws <alias>` to filter results to a workspace
+  - `--ws all` to force global behavior (optional; may be default)
+
+Qualified IDs may be used as input:
+- `<ws>:<id>` (example: `e2e:task-12`)
+
+If a user provides an unqualified ID and it is ambiguous globally:
+- mdkg MUST error and suggest qualified IDs.
+
+## Exit codes (v1)
+
+- `0` success
+- `1` general error / invalid usage
+- `2` validation error (frontmatter/schema/graph integrity)
+- `3` not found (node/workspace/template not found)
+- `4` index error (index build failure)
+
+## Output conventions
+
+- Human-readable output to stdout.
+- Errors to stderr.
+- Commands should be script-friendly:
+  - concise outputs for single items
+  - predictable formatting
+  - optional `--json` output later (not required for v1)
+  - 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)
+
+### Initialization
+- `mdkg init`
+  - creates `.mdkg/` directory structure at root
+  - 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
+
+### Guide
+- `mdkg guide`
+  - prints `.mdkg/core/guide.md` to stdout
+
+### Workspace management (registered, no discovery)
+- `mdkg workspace ls`
+- `mdkg workspace add <alias> <path>`
+- `mdkg workspace rm <alias>`
+
+### Indexing
+- `mdkg index`
+  - rebuild global cache `.mdkg/index/global.json`
+  - strict by default (fails on invalid frontmatter)
+  - optional `--tolerant` to skip invalid nodes (escape hatch)
+
+### Create nodes
+- `mdkg new <type> "<title>" [flags]`
+  - uses global templates (root-only) via token substitution
+  - writes into the appropriate workspace-local `.mdkg/<area>/` folder
+  - updates index if necessary
+
+Common flags:
+- `--ws <alias>` (default `root`)
+- `--status <status>` (work items)
+- `--priority <0..9>` (work items)
+- `--epic <id>`
+- `--parent <id>`
+- `--relates <id,id,...>`
+- `--blocked-by <id,id,...>`
+- `--blocks <id,id,...>`
+- `--prev <id>`
+- `--next <id>`
+- `--links <ref,ref,...>`
+- `--artifacts <ref,ref,...>`
+- `--refs <id,id,...>`
+- `--aliases <text,text,...>`
+- `--template <set>` (default from config)
+
+### Read/search
+- `mdkg show <id-or-qid>`
+- `mdkg search "<query>" [--type <type>] [--status <status>] [--ws <alias>]`
+  - 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 <...>]`
+
+### Packs (core feature)
+- `mdkg pack <id-or-qid> [--depth <n>] [--verbose] [--edges <keys>] [--format md|json|toon|xml] [--out <path>] [--ws <alias>]`
+  - `--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`
+
+### Next priority
+- `mdkg next [<id-or-qid>] [--ws <alias>]`
+  - If `<id>` provided: follow `next` if present; otherwise fall back to priority-based selection.
+  - If no `<id>` provided: use priority-based selection (and optionally an epic filter in future).
+
+### Checkpoints
+- `mdkg checkpoint new "<title>" [--ws <alias>] [--relates <id,...>] [--scope <id,...>]`
+  - creates a `chk-*` node from template
+  - designed as a phase summary / compression node
+
+### Validation and formatting
+- `mdkg validate`
+  - strict frontmatter + graph integrity checks (exit code 2 on failure)
+- `mdkg format`
+  - normalize frontmatter formatting and casing
+  - avoid destructive body edits

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

@@ -0,0 +1,97 @@
+---
+id: rule-4
+type: rule
+title: mdkg repo safety (ignore rules, publish safety, deployment safety)
+tags: [mdkg, publishing, safety]
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: 2026-01-06
+updated: 2026-01-14
+---
+
+# Repo safety and ignores
+
+mdkg content may contain sensitive notes and internal project planning. This rule defines how to prevent `.mdkg/` content from leaking into build artifacts, containers, and npm packages.
+
+## Safety goals
+
+- `.mdkg/` must not be shipped to production deployments.
+- `.mdkg/` must not be published to npm.
+- `.mdkg/index/` must never be committed.
+
+## Git ignore requirements
+
+The repo MUST ignore at minimum:
+
+- `node_modules/`
+- `dist/`
+- `.mdkg/index/`
+- `.mdkg/pack/`
+
+Recommended `.gitignore` entries:
+- `.mdkg/index/`
+- `.mdkg/index/**`
+- `.mdkg/pack/`
+
+## npm publish safety (required)
+
+The npm package MUST publish only the compiled CLI output and essential docs.
+
+Required approach:
+- Use `package.json` `"files"` whitelist to ship only:
+  - `dist/`
+  - `README.md`
+  - `LICENSE`
+
+This approach is preferred over blacklists.
+
+Additional belt-and-suspenders:
+- Add `.npmignore` that excludes `.mdkg/` and other repo internals, even if `"files"` exists.
+
+## Container and deployment safety (recommended)
+
+If the repo is containerized:
+- `.dockerignore` SHOULD exclude:
+  - `.mdkg/`
+  - `.mdkg/index/`
+  - `node_modules/`
+  - `dist/` (if built in container)
+  - any other local artifacts
+
+For application builds:
+- Build tooling SHOULD exclude `.mdkg/` (e.g., tsconfig excludes, bundlers exclude dot-folders).
+
+## mdkg init behavior
+
+`mdkg init` MAY offer optional flags to append ignore entries:
+
+- `--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.
+- Index files may contain extracted metadata and could expose sensitive strings.
+- Index files MUST be ignored from git.
+- Index rebuild should be deterministic and safe to regenerate at any time.
+
+## Workspace safety
+
+Workspace-local `.mdkg/` directories (near code) should follow the same rules:
+- the content is source-of-truth docs (tracked)
+- the workspace-local index folder (if present) should be ignored
+- templates remain global (root) in v1
+
+## Summary checklist
+
+- ✅ `.mdkg/index/` ignored
+- ✅ npm publishes only `dist/`, `README.md`, `LICENSE`
+- ✅ optional `.npmignore` excludes `.mdkg/`
+- ✅ `.dockerignore` excludes `.mdkg/` when applicable

package/dist/init/core/rule-5-release-and-versioning.md

@@ -0,0 +1,82 @@
+---
+id: rule-5
+type: rule
+title: mdkg release and versioning (semver, publish checklist)
+tags: [mdkg, npm, release, semver]
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: 2026-01-06
+updated: 2026-01-14
+---
+
+# Release and versioning
+
+mdkg follows SemVer for CLI stability and long-term compatibility.
+
+## SemVer policy
+
+- MAJOR: breaking CLI contract changes (flags/outputs removed or changed)
+- MINOR: new commands/features that are backwards compatible
+- PATCH: bug fixes and internal refactors with no contract changes
+
+Configuration and schema versioning:
+- `.mdkg/config.json` contains a `schema_version`.
+- mdkg MUST support migrating older schemas to the current schema in a deterministic way.
+- Backwards compatibility matters more for config and docs than for internal index formats.
+
+## Release artifacts
+
+The npm package MUST include:
+- `dist/` compiled output
+- `README.md`
+- `LICENSE`
+
+It MUST NOT include:
+- `.mdkg/` docs
+- `.mdkg/index/`
+- source code (optional; can be included later, but not required)
+
+## Release checklist (v1)
+
+1) Ensure clean working tree
+- no uncommitted changes
+- all `.mdkg/index/` ignored
+
+2) Rebuild and validate
+- run `mdkg index`
+- run `mdkg validate`
+- run a pack smoke test (example):
+  - `mdkg pack task-1 --verbose --out /tmp/mdkg-pack.md`
+
+3) Update version
+- bump `package.json` version (semver)
+
+4) Update changelog (recommended)
+- add a short entry describing changes
+
+5) Build
+- run `npm run build` (or equivalent)
+- confirm `dist/cli.js` exists and is executable as a node script
+
+6) Confirm publish whitelist
+- verify `package.json` `"files"` includes only expected files
+- optionally run `npm pack` and inspect tarball contents
+
+7) Publish
+- `npm publish`
+
+8) Tag and push
+- create git tag matching version (example `v0.1.0`)
+- push commits and tags
+
+## Release notes guidance
+
+Release notes should call out:
+- new commands / flags
+- changes to pack behavior
+- changes to config schema (and how migration behaves)
+- new node types or template changes