mdkg 0.0.8 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to mdkg are documented here.
+
+This project follows a pragmatic changelog style inspired by Keep a Changelog. Versions use npm package versions.
+
+## 0.1.0 - 2026-05-12
+
+### Added
+
+- Added conservative `mdkg upgrade` for existing workspaces.
+- Added `.mdkg/init-manifest.json` ownership tracking for managed init assets.
+- Added v0.0.9 seed fingerprints so clean older workspaces can safely adopt current init docs, templates, and default skills.
+- Added `npm run smoke:upgrade` for packed-package upgrade verification in temporary workspaces.
+
+### Changed
+
+- `mdkg upgrade` defaults to dry-run; `mdkg upgrade --apply` is the only mutating upgrade path.
+- Agent-enabled workspaces can receive safe managed default skill upgrades and mirror refreshes during upgrade.
+- Publish readiness now checks packaged init manifests and runs upgrade smoke before publish.
+
+## 0.0.9 - 2026-05-12
+
+### Added
+
+- Added generic agent workflow file support for `SPEC.md`, `WORK.md`, `WORK_ORDER.md`, `RECEIPT.md`, `FEEDBACK.md`, `DISPUTE.md`, and `PROPOSAL.md`.
+- Added `mdkg new <agent-file-type> ... --id <portable-id>` for semantic ids such as `agent.image-worker` and `work.generate-image`.
+- Added validation support for `pricing_model: included`.
+- Added validation support for `proposal_kind: skill_update` targeting `skill.<slug>` refs.
+- Added generic skill extension output under `extensions`, with `ochatr_*` metadata mapped to `extensions.ochatr`.
+- Added a non-mutating npm `postinstall` hint that points users to `mdkg --help` and prints shell PATH guidance only when needed.
+- Added `docs/agent-runtime-0.0.9-handoff.md` to document the runtime migration path from implementation-specific naming to generic agent workflow naming.
+- Added `npm run smoke:matrix` to pack mdkg, install it into an isolated temporary npm prefix, and exercise the command matrix plus onboarding workflows from the packaged CLI.
+
+### Changed
+
+- Renamed the remaining public Omni file-type surface to generic agent workflow language.
+- Kept `mdkg init --omni` only as hidden migration guidance to `mdkg init --agent`.
+- Updated README and command matrix version references to `0.0.9`.
+- Removed stale prepublish wording and absolute local README links.
+- Removed `AGENT_PROMPT_SNIPPET.md` and distilled its startup rules into `AGENT_START.md`, making `AGENT_START.md` the single first-hop agent onboarding doc.
+- Treated ochatr.ai metadata as a vendor extension pattern rather than the base mdkg schema name.
+- Added npm `prepack` and `prepublishOnly` guards so release commands fail if the built CLI or init assets are missing.
+- Included `CHANGELOG.md` and `CONTRIBUTING.md` in the npm package because README links to them.
+
+### Fixed
+
+- Fixed strict validation gaps for room-runtime-style skill proposals and included pricing.
+- Fixed docs drift between published `0.0.8`, local source version, and the 0.0.9 release target.
+
+### Verification Status
+
+- Passed: `npm ci` with `NPM_CONFIG_CACHE=/private/tmp/mdkg-npm-cache`.
+- Passed: `npm run build`.
+- Passed: `npm run test` with 306 tests.
+- Passed: `npm run cli:check`.
+- Passed: `node dist/cli.js validate`.
+- Passed: `npm run smoke:consumer`.
+- Passed: `npm run smoke:matrix`.
+- Passed: `npm pack --dry-run --json`; tarball includes `dist/cli.js`, compiled command/core/graph/pack/template/util files, `dist/init/`, `CHANGELOG.md`, `CONTRIBUTING.md`, `README.md`, `LICENSE`, package metadata, and `scripts/postinstall.js`.
+- Passed: `npm publish --dry-run`; `prepublishOnly` and `prepack` both completed successfully.
+- Confirmed before publish: npm registry latest remains `mdkg@0.0.8`.
+
+## 0.0.8
+
+- Published npm baseline before the 0.0.9 agent workflow release work.
+- Does not include agent workflow file types, mutation JSON receipt expansion, workspace enable/disable, or postinstall guidance.
+
+## 0.0.7 and earlier
+
+- Historical local and published release line for mdkg's initial CLI, graph, pack, skill, and agent-bootstrap work.

package/CONTRIBUTING.md

@@ -0,0 +1,124 @@
+# Contributing to mdkg
+
+mdkg is a local-first CLI for deterministic project memory. Contributions should preserve that shape: file-based, inspectable in git, deterministic when possible, and useful to both humans and agents.
+
+## Prompt Requests Before Pull Requests
+
+The preferred contribution path is a Prompt Request: describe intent clearly enough that a maintainer, human contributor, or coding agent can turn it into a correct patch.
+
+This is inspired by the OpenClaw creator's framing of Prompt Requests over Pull Requests. The point is not to reject code; it is to make user intent first-class. Many useful contributors know the workflow problem better than the codebase. mdkg should capture that intent before debating implementation details.
+
+Use a Prompt Request when you want to propose:
+- a new command or flag
+- a docs or onboarding improvement
+- a validation rule
+- a workflow standard
+- a bug report with expected behavior
+- an agent-facing convention or template
+
+A good Prompt Request includes:
+- the goal in plain language
+- the current behavior or gap
+- the desired behavior
+- one or two example commands or markdown snippets
+- acceptance criteria
+- any constraints, such as backwards compatibility or public naming
+
+Code Pull Requests are still welcome when the implementation is clear, scoped, tested, and linked to the intent it serves.
+
+## Public Naming
+
+mdkg's public standard language is generic agent workflow language.
+
+Use:
+- `agent workflow files`
+- `agent workflow docs`
+- `mdkg init --agent`
+- `skill.<slug>` for skill proposal targets
+- `extensions.<vendor>` for vendor extension metadata
+
+Avoid new public API or docs language that makes mdkg look tied to one product or runtime. ochatr.ai is a pioneering adopter and may use `ochatr_*` extension metadata, but the base mdkg schema should stay vendor-neutral.
+
+## Development Loop
+
+Install dependencies when npm is available:
+
+```bash
+npm install
+```
+
+Core checks:
+
+```bash
+npm run build
+npm run test
+npm run cli:check
+node dist/cli.js validate
+```
+
+Release smoke checks:
+
+```bash
+npm run smoke:consumer
+npm pack --dry-run
+```
+
+If the local toolchain is incomplete, document exactly what was blocked and run the checks that are still possible, such as:
+
+```bash
+git diff --check
+node --check scripts/postinstall.js
+```
+
+## Working in the mdkg Repo
+
+This repo dogfoods mdkg. Before a substantial change:
+
+1. Read `AGENT_START.md`.
+2. Inspect relevant source and tests.
+3. Use `CLI_COMMAND_MATRIX.md` for the command surface.
+4. Keep source behavior and docs aligned.
+5. Add focused tests for new user-visible behavior.
+6. Run `mdkg validate` after building when possible.
+
+Do not commit generated index or pack outputs. Keep `.mdkg/index/` and `.mdkg/pack/` ignored.
+
+## Change Requirements
+
+Good patches are:
+- small enough to review
+- explicit about public interface changes
+- covered by focused tests
+- documented in `README.md`, `CLI_COMMAND_MATRIX.md`, or `CHANGELOG.md` when behavior changes
+- careful with existing dirty worktree changes
+
+For agent workflow files, update tests and fixtures when changing:
+- accepted frontmatter fields
+- validation rules
+- `mdkg new` scaffolding
+- pack/search/show output
+
+For release work, update:
+- `package.json`
+- `package-lock.json`
+- `README.md`
+- `CLI_COMMAND_MATRIX.md`
+- `CHANGELOG.md`
+- init assets under `assets/init/` when generated starter docs change
+
+## Pull Request Guidance
+
+When submitting code, include:
+- linked Prompt Request or short intent statement
+- summary of behavior changes
+- tests run and any blocked checks
+- docs updated or reason docs were not needed
+- compatibility notes for existing mdkg repos
+
+Do not include unrelated formatting churn or generated artifacts unless the change requires them.
+
+## Security and Secrets
+
+Do not put secrets in mdkg nodes, packs, events, fixtures, or test outputs. mdkg is project memory, not a secret store.
+
+Report security-sensitive issues privately until a safe disclosure path is established.

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.6`
+Current package version in source: `0.1.0`
 
 ## The product shape
 
@@ -31,8 +31,6 @@ If a repo needs repeatable procedures, author them as first-class skills under `
 
 ## Install
 
-Once published:
-
 ```bash
 npm i -g mdkg
 # or
@@ -59,12 +57,34 @@ mdkg init --agent
 
 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/`.
 
+Preview safe scaffold upgrades in an existing mdkg workspace:
+
+```bash
+mdkg upgrade
+mdkg upgrade --json
+```
+
+Apply only after reviewing the receipt:
+
+```bash
+mdkg upgrade --apply
+```
+
+Upgrade is intentionally conservative. It creates missing managed startup docs and updates unchanged mdkg seed assets, but preserves customized docs, templates, skills, and core files as reported conflicts. Agent-enabled workspaces also get safe default skill upgrades and skill mirror refreshes; non-agent workspaces do not gain skills, events, or mirrors implicitly.
+
 Create a task:
 
 ```bash
 mdkg new task "bootstrap cli" --status todo --priority 1 --tags cli,build
 ```
 
+Create an agent workflow document with a semantic portable id:
+
+```bash
+mdkg new spec "image worker" --id agent.image-worker
+mdkg new work "generate image" --id work.generate-image
+```
+
 Inspect the current truth:
 
 ```bash
@@ -94,8 +114,6 @@ mdkg task update task-1 --add-artifacts tests://unit.txt --add-tags release
 mdkg task done task-1 --checkpoint "release readiness milestone"
 ```
 
-`mdkg task ...` remains limited to `task`, `bug`, and `test`, but `skills: [...]` is valid metadata on all work items (`epic`, `feat`, `task`, `bug`, `checkpoint`, `test`). mdkg-generated work items should validate and round-trip through the task mutators without manual frontmatter repair.
-
 Ensure and append baseline event memory:
 
 ```bash
@@ -115,13 +133,13 @@ mdkg skill validate release-readiness
 ## LLM-readable onboarding artifacts
 
 The root docs below are the canonical fast-start set for humans and agents:
-- [`AGENT_START.md`](/Users/nicholasreames/Git/mdkg/AGENT_START.md)
-- [`llms.txt`](/Users/nicholasreames/Git/mdkg/llms.txt)
-- [`AGENT_PROMPT_SNIPPET.md`](/Users/nicholasreames/Git/mdkg/AGENT_PROMPT_SNIPPET.md)
-- [`PACK_EXAMPLES.md`](/Users/nicholasreames/Git/mdkg/PACK_EXAMPLES.md)
-- [`MANUAL_BEHAVIOR_AUDIT.md`](/Users/nicholasreames/Git/mdkg/MANUAL_BEHAVIOR_AUDIT.md)
-- [`CLI_COMMAND_MATRIX.md`](/Users/nicholasreames/Git/mdkg/CLI_COMMAND_MATRIX.md)
-- [`COVERAGE_HARDENING_MATRIX.md`](/Users/nicholasreames/Git/mdkg/COVERAGE_HARDENING_MATRIX.md)
+- [`AGENT_START.md`](AGENT_START.md)
+- [`llms.txt`](llms.txt)
+- [`PACK_EXAMPLES.md`](PACK_EXAMPLES.md)
+- [`CLI_COMMAND_MATRIX.md`](CLI_COMMAND_MATRIX.md)
+- [`COVERAGE_HARDENING_MATRIX.md`](COVERAGE_HARDENING_MATRIX.md)
+- [`CHANGELOG.md`](CHANGELOG.md)
+- [`CONTRIBUTING.md`](CONTRIBUTING.md)
 
 ## Repository shape
 
@@ -139,6 +157,7 @@ mdkg lives under a hidden root directory:
 
 These are the commands new users and agents should learn first:
 - `mdkg init`
+- `mdkg upgrade`
 - `mdkg new`
 - `mdkg search`
 - `mdkg show`
@@ -186,7 +205,6 @@ Current source behavior:
   - `mdkg skill search "<query>" --xml|--toon|--md`
   - `mdkg skill show <slug> --xml|--toon|--md`
 - work items may reference `skills: [slug,...]`
-- `skills` is valid on all work items (`epic`, `feat`, `task`, `bug`, `checkpoint`, `test`)
 - packs may include skills with `--skills` and `--skills-depth`
 - mdkg indexes and discovers skills but does not execute skill scripts
 - `SKILL.md` is canonical
@@ -202,6 +220,21 @@ This repo now dogfoods three internal skills:
 - `build-pack-and-execute-task`
 - `verify-close-and-checkpoint`
 
+Optional skill metadata with prefixes such as `ochatr_*` is treated as vendor extension data. Structured skill output exposes it under `extensions.ochatr` while keeping the top-level `ochatr` field as a compatibility alias introduced in 0.0.9. ochatr.ai is a pioneering adopter of this extension pattern, not the name of the base mdkg standard.
+
+## Agent workflow files
+
+mdkg recognizes a small set of canonical agent workflow documents:
+- `SPEC.md` for agent, package, or runtime specifications
+- `WORK.md` for reusable work contracts
+- `WORK_ORDER.md` for concrete requests against work contracts
+- `RECEIPT.md` for completed work output and artifacts
+- `FEEDBACK.md`, `DISPUTE.md`, and `PROPOSAL.md` for review loops
+
+Use `mdkg new spec|work|work_order|receipt|feedback|dispute|proposal "<title>"` to scaffold them. `--id <portable-id>` is available for these types when semantic ids such as `agent.image-worker` or `work.generate-image` are preferred.
+
+Relational templates contain editable placeholder refs. `spec` and `work` scaffold as validation-clean standalone docs; `work_order`, `receipt`, `feedback`, `dispute`, and `proposal` need real refs before strict `mdkg validate` passes.
+
 ## Current direction
 
 This release includes:
@@ -214,6 +247,7 @@ This release includes:
 - latest-checkpoint resolver + index hint
 - events JSONL validation
 - XML / TOON / Markdown output for node and skill list/search/show
+- agent workflow file types and semantic `mdkg new --id` support
 - product-specific skill mirrors for Codex/OpenAI and Claude
 - shared `AGENT_START.md` startup guidance
 
@@ -222,7 +256,6 @@ Current direction:
 - use `init --agent` for deeper AI-agent bootstrap
 - keep `pack <id>` at the center of the human/agent loop
 - use `mdkg task ...` for structured state changes and markdown edits for narrative/body content
-- keep validation strict and fix schema drift instead of papering over mdkg-generated inconsistencies
 - make event logging guided instead of purely manual
 - dogfood real skills inside the repo
 - make skill authoring first-class through `mdkg skill`
@@ -245,6 +278,8 @@ Use these defaults:
 
 ## Contributing
 
+Start with [`CONTRIBUTING.md`](CONTRIBUTING.md). mdkg prefers Prompt Requests before Pull Requests: contributors can submit intent, workflows, prompts, and acceptance criteria without needing to write code first.
+
 This repo dogfoods mdkg itself. The behavior source of truth is the combination of:
 - source under `src/`
 - tests under `tests/`