mdkg 0.3.1 → 0.3.3

package/dist/init/README.md

@@ -8,7 +8,7 @@ mdkg is pre-v1 public alpha software. Graph, cache, bundle, and DAL contracts ma
 
 - `core/`: rules, operating guide, and pinned docs
 - `design/`: product/engineering decision records
-- `work/`: epics, tasks, bugs, tests, checkpoints
+- `work/`: epics, tasks, bugs, tests, spikes, checkpoints
 - `templates/`: default node templates
 - `archive/`: sidecar metadata and deterministic compressed source/artifact caches
 - `bundles/`: optional committed full graph snapshot bundles
@@ -20,6 +20,7 @@ mdkg is pre-v1 public alpha software. Graph, cache, bundle, and DAL contracts ma
 
 ```bash
 mdkg upgrade
+mdkg index
 mdkg new task "..." --status todo --priority 1
 mdkg search "..."
 mdkg show <id>
@@ -34,18 +35,34 @@ mdkg fix plan --json
 mdkg validate
 ```
 
-This repo is already initialized. Use `mdkg upgrade` to preview safe scaffold updates, `mdkg new` to create work, `mdkg new goal "..."` plus `mdkg goal select/current/next/claim/evaluate` for recursive long-running objectives, `mdkg search`/`mdkg show` to inspect graph state, `mdkg capability ...` to inspect cached skill/spec/work/core/design capabilities, `mdkg spec ...` for focused optional SPEC records, `mdkg capability resolve ...` to rank local and subgraph capabilities, `mdkg archive ...` to register source/artifact sidecars, `mdkg work ...` to create work contract/order/receipt semantic mirrors and deterministic trigger/verification records, `mdkg bundle ...` to create full graph snapshot bundles, `mdkg subgraph ...` to register read-only child graph planning views, `mdkg pack <id>` to build deterministic context, and `mdkg validate` before closeout.
+This repo is already initialized. Use `mdkg upgrade` to preview safe scaffold updates, `mdkg index` to create or refresh generated graph/skill/capability/subgraph and SQLite caches after init, `mdkg new` to create work, `mdkg new goal "..."` plus `mdkg goal activate/current/next/claim/evaluate` for recursive long-running objectives, `mdkg search`/`mdkg show` to inspect graph state, `mdkg capability ...` to inspect cached skill/spec/work/core/design capabilities, `mdkg spec ...` for focused optional SPEC records, `mdkg capability resolve ...` to rank local and subgraph capabilities, `mdkg archive ...` to register source/artifact sidecars, `mdkg work ...` to create work contract/order/receipt semantic mirrors and deterministic trigger/verification records, `mdkg bundle ...` to create full graph snapshot bundles, `mdkg subgraph ...` to register read-only child graph planning views, `mdkg pack <id>` to build deterministic context, and `mdkg validate` before closeout.
 
 Use `mdkg status --json` for a read-only operator summary of Git, graph,
 selected-goal, project DB, and generated-cache health before mutating work. Use
 `mdkg doctor --strict --json` for typed diagnostic checks in CI or agent
-orchestration. These commands inspect state; they do not apply repairs.
+orchestration. These commands inspect state; they do not apply repairs. After a
+fresh init, run `mdkg index` first so strict doctor can load generated caches.
 
 Use `mdkg fix plan --json` for dry-run repair guidance. It reports generated
 index/cache repair hints, missing graph references, and duplicate local ids as
 receipt-shaped planned changes with risk levels and `apply_supported: false`.
 `fix apply` is not exposed; repair application is intentionally deferred.
 
+Use research spikes for investigation and planning work that should produce a
+reviewable recommendation before implementation:
+
+```bash
+mdkg new spike "research docs launch workflow" --status todo --priority 1
+mdkg task start spike-1
+mdkg show spike-1
+```
+
+Spikes use the existing task lifecycle and goal routing. They do not perform web
+search, execute research, create follow-up nodes, or generate `SKILL.md` files
+automatically. Record sources, findings, recommendations, follow-up node ideas,
+and skill candidates in the spike body, then create follow-up tasks or tests
+intentionally with `mdkg new task ...` or `mdkg new test ...`.
+
 Agent workflow docs can use semantic ids:
 
 ```bash

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

@@ -67,10 +67,19 @@ It MUST NOT include:
 - verify `package.json` `"files"` includes only expected files
 - optionally run `npm pack` and inspect tarball contents
 
-7) Publish
-- `npm publish`
-
-8) Tag and push
+7) Confirm npm auth
+- if using an exported `NPM_TOKEN`, create a temporary npm userconfig that
+  references `${NPM_TOKEN}` literally:
+  `//registry.npmjs.org/:_authToken=${NPM_TOKEN}`
+- run `npm whoami --registry=https://registry.npmjs.org/ --userconfig=/private/tmp/mdkg-npm-publish.npmrc`
+- do not print the token, do not commit the temp userconfig, and do not add
+  unsupported `always-auth` config
+
+8) Publish
+- `npm publish --registry=https://registry.npmjs.org/ --userconfig=/private/tmp/mdkg-npm-publish.npmrc`
+- omit `--userconfig` only when an existing npm login has already been verified
+
+9) Tag and push
 - create git tag matching version (example `v0.1.0`)
 - push commits and tags
 

package/dist/init/init-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.3.1",
+  "mdkg_version": "0.3.3",
   "files": [
     {
       "path": ".mdkg/config.json",
@@ -46,7 +46,7 @@
     {
       "path": ".mdkg/core/rule-5-release-and-versioning.md",
       "category": "core",
-      "sha256": "e97b00aa3ade29011f1f2b482042ec292f74aad8b1d72e2f8e691cdeca5d4f70"
+      "sha256": "d7862806f999ae23b1d8bc3446f8c81b3a7fdd7d87920d966f59795a84978a03"
     },
     {
       "path": ".mdkg/core/rule-6-templates-and-schemas.md",
@@ -61,7 +61,7 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "0661196763bf05681523a576fcd0a29138ccc36df4f48dad7ba16a1f4b7b0418"
+      "sha256": "68b5f4d2d04a4dc9a062e54a594d684b3816c0b614079eb6b08f0dca16fd0b47"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
@@ -71,7 +71,7 @@
     {
       "path": ".mdkg/skills/pursue-mdkg-goal/SKILL.md",
       "category": "default_skill",
-      "sha256": "fd64f666fb1329c392ff0979ed9999b71ad948cbca6a191502eb2cdfd76ec825"
+      "sha256": "2bc888092d95b362e402494af4dbe6909204bd5578613d6159753a84efaae16d"
     },
     {
       "path": ".mdkg/skills/select-work-and-ground-context/SKILL.md",
@@ -163,6 +163,11 @@
       "category": "template",
       "sha256": "8c96e0b6dafa65acb83a2d84519e05a7354896aec8991c148650e9ec58196c77"
     },
+    {
+      "path": ".mdkg/templates/default/spike.md",
+      "category": "template",
+      "sha256": "ac805dca7e6edcdad35e24b615dc7399cbae3bed676b9da57e24a393eb425245"
+    },
     {
       "path": ".mdkg/templates/default/task.md",
       "category": "template",
@@ -241,7 +246,7 @@
     {
       "path": "AGENT_START.md",
       "category": "startup_doc",
-      "sha256": "cf58e37c72be2593f1d920520dbdc6e316182bfda5c49837443a8b18024504c7"
+      "sha256": "46e734b6eae92eb957c3e29fb4d206e4be3fd6d32dd00e888e01a0dc75979428"
     },
     {
       "path": "AGENTS.md",
@@ -256,7 +261,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "a9a7133e5a7c9a07a6814c679d04637370ea144eac19a6500980a37a2c4199f5"
+      "sha256": "7f27715427a6762ef987fb872c9e09976075c76fddac68c4df89387e5b8a6909"
     },
     {
       "path": "llms.txt",

package/dist/init/skills/default/pursue-mdkg-goal/SKILL.md

@@ -27,7 +27,8 @@ Move one durable mdkg goal forward without losing scope, evidence, or user inten
 ## Steps
 
 1. Resolve the goal:
-   - If a goal id is provided, run `mdkg goal select <goal-id>`.
+   - If a goal id is provided and you are beginning durable work on it, run `mdkg goal activate <goal-id>`.
+   - Use `mdkg goal select <goal-id>` only when you need a local pointer without changing lifecycle state.
    - Otherwise run `mdkg goal current`.
    - If the result is missing or ambiguous, ask the user to select a goal.
 2. Inspect the goal with `mdkg goal show <goal-id>` and build context with `mdkg pack <goal-id>`.

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

@@ -0,0 +1,81 @@
+---
+id: {{id}}
+type: spike
+title: {{title}}
+status: {{status}}
+priority: {{priority}}
+epic: {{epic}}
+parent: {{parent}}
+prev: {{prev}}
+next: {{next}}
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+blocked_by: []
+blocks: []
+refs: []
+aliases: []
+skills: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Research Question
+
+State the question this spike must answer.
+
+# Context And Constraints
+
+- constraint 1
+- constraint 2
+
+# Search Plan
+
+- source or query 1
+- source or query 2
+
+# Findings
+
+- finding 1
+- finding 2
+
+# Options And Tradeoffs
+
+- option 1: tradeoff
+- option 2: tradeoff
+
+# Recommendation
+
+Summarize the recommended direction and why.
+
+# Follow-Up Nodes To Create
+
+- task/test/decision candidate 1
+- task/test/decision candidate 2
+
+# Skill Candidates
+
+- skill candidate 1
+- skill candidate 2
+
+# Data Structures And Algorithms Notes
+
+- note 1
+
+# UX Notes
+
+- note 1
+
+# Security Notes
+
+- note 1
+
+# mdkg.dev Launch Implications
+
+- implication 1
+
+# Evidence And Sources
+
+- source 1

package/dist/pack/order.js

@@ -21,9 +21,10 @@ const FALLBACK_TYPES = [
     "feat",
     "task",
     "bug",
+    "spike",
     "checkpoint",
 ];
-const WORK_TYPES = ["goal", "epic", "feat", "task", "bug", "checkpoint"];
+const WORK_TYPES = ["goal", "epic", "feat", "task", "bug", "spike", "checkpoint"];
 function idNumber(id) {
     const match = id.match(/-(\d+)$/);
     if (!match) {
@@ -76,7 +77,7 @@ function buildOrderKey(index, rootQid, qid, depths) {
     const node = index.nodes[qid];
     const root = index.nodes[rootQid];
     const depth = depths.get(qid);
-    const rootIsTask = root.type === "task" || root.type === "bug";
+    const rootIsTask = root.type === "task" || root.type === "bug" || root.type === "spike";
     if (qid === rootQid) {
         return {
             group: 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdkg",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {
@@ -29,6 +29,8 @@
     "smoke:fix-plan": "npm run build && node scripts/smoke-fix-plan.js",
     "smoke:branch-conflicts": "npm run build && node scripts/smoke-branch-conflicts.js",
     "smoke:command-docs": "npm run build && node scripts/smoke-command-docs.js",
+    "smoke:spike": "npm run build && node scripts/smoke-spike.js",
+    "smoke:goal-lifecycle": "npm run build && node scripts/smoke-goal-lifecycle.js",
     "smoke:bundle": "npm run build && node scripts/smoke-bundle.js",
     "smoke:bundle-import": "npm run smoke:subgraph",
     "smoke:visibility": "npm run build && node scripts/smoke-visibility.js",
@@ -39,7 +41,7 @@
     "cli:check": "npm run build && node scripts/cli_help_snapshot.js --check",
     "cli:contract": "npm run build && node scripts/generate-command-contract.js --check",
     "prepack": "npm run build && node scripts/assert-publish-ready.js",
-    "prepublishOnly": "npm run test && npm run cli:check && npm run cli:contract && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && npm run smoke:upgrade && npm run smoke:init && npm run smoke:capabilities && npm run smoke:db && npm run smoke:db-queue && npm run smoke:db-queue-cli && npm run smoke:db-events && npm run smoke:db-materializer && npm run smoke:db-snapshot && npm run smoke:archive-work && npm run smoke:work-invocation && npm run smoke:cli-ux-polish && npm run smoke:operator-health && npm run smoke:fix-plan && npm run smoke:branch-conflicts && npm run smoke:command-docs && npm run smoke:bundle && npm run smoke:subgraph && npm run smoke:visibility && npm run smoke:sqlite && npm run smoke:parallel && npm run smoke:goal && node scripts/assert-publish-ready.js",
+    "prepublishOnly": "npm run test && npm run cli:check && npm run cli:contract && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && npm run smoke:upgrade && npm run smoke:init && npm run smoke:capabilities && npm run smoke:db && npm run smoke:db-queue && npm run smoke:db-queue-cli && npm run smoke:db-events && npm run smoke:db-materializer && npm run smoke:db-snapshot && npm run smoke:archive-work && npm run smoke:work-invocation && npm run smoke:cli-ux-polish && npm run smoke:operator-health && npm run smoke:fix-plan && npm run smoke:branch-conflicts && npm run smoke:command-docs && npm run smoke:spike && npm run smoke:goal-lifecycle && npm run smoke:bundle && npm run smoke:subgraph && npm run smoke:visibility && npm run smoke:sqlite && npm run smoke:parallel && npm run smoke:goal && node scripts/assert-publish-ready.js",
     "postinstall": "node scripts/postinstall.js",
     "smoke:subgraph": "npm run build && node scripts/smoke-subgraph.js"
   },