mdkg 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -12,6 +12,52 @@ mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL con
 
 - No changes yet.
 
+## 0.3.2 - 2026-06-16
+
+### Added
+
+- Added first-class research spike work-node support with `mdkg new spike`,
+  `spike-#` ids, `.mdkg/work/` storage, and compatibility with existing
+  `mdkg task start/update/done` lifecycle commands.
+- Added spike participation in `mdkg next`, `mdkg goal next`, `mdkg goal claim`,
+  list/search/show structured exports, deterministic packs, goal-root pack
+  closure, and generated command contract metadata.
+- Added a default spike template for research question, context, search plan,
+  findings, options/tradeoffs, recommendation, follow-up nodes, skill
+  candidates, domain notes, mdkg.dev launch implications, and evidence/sources.
+- Added packed `smoke:spike` coverage that installs mdkg from a tarball in a
+  temp prefix, creates a fresh repo, exercises spike lifecycle and goal routing,
+  verifies structured exports and pack formats, creates follow-up task/test
+  nodes, and confirms no automatic skill generation occurs.
+- Added mdkg.dev dogfood research spike nodes and follow-up roadmap nodes so
+  launch planning can proceed from evidence-backed spikes after this release.
+
+### Changed
+
+- Updated README, `CLI_COMMAND_MATRIX.md`, init assets, help text, command docs,
+  and publish-readiness assertions to describe spikes as actionable research
+  work nodes, not autonomous web-search or file-generation agents.
+- Hardened init and upgrade compatibility so fresh and upgraded repos receive
+  the bundled spike template while customized spike templates are preserved.
+- Hardened spike pack/export behavior across JSON, Markdown, XML, and toon
+  pack formats plus public visibility filtering for spike archive references.
+- Hardened validation and fix-plan UX for malformed spikes: invalid ids,
+  statuses, priorities, missing refs, duplicate spike ids, and missing spike
+  body sections now have explicit test coverage and read-only repair guidance
+  where existing fix-plan families apply.
+- Extended `mdkg fix plan refs` to inspect indexed `links`, `artifacts`, and
+  `refs` fields in addition to custom attributes, so missing archive refs in
+  normal node metadata appear in repair plans.
+
+### Security
+
+- Kept spikes as human/agent-authored Markdown work nodes only. This release
+  does not add a `mdkg spike ...` namespace, automatic web search, automatic
+  follow-up node creation, automatic `SKILL.md` generation, or repair apply
+  behavior.
+- Preserved dry-run-only repair planning: spike-related fix guidance remains
+  receipt-shaped, non-mutating, and `apply_supported: false`.
+
 ## 0.3.1 - 2026-06-11
 
 ### Added

package/CLI_COMMAND_MATRIX.md

@@ -1,7 +1,7 @@
 # CLI Command Matrix
 
 as_of: 2026-06-06
-package_version_in_source: 0.2.0
+package_version_in_source: 0.3.1
 source: live help from `src/cli.ts`, runtime command handlers, and `dec-15`..`dec-18`
 status: canonical single-source command and flag reference for mdkg
 
@@ -101,6 +101,7 @@ Notes:
 - removed flags `--llm`, `--agents`, `--claude`, and `--omni` fail before mutation with guidance to use `mdkg init --agent`
 - published bootstrap config is root-only by default
 - `--agent` creates `AGENT_START.md`, `AGENTS.md`, `CLAUDE.md`, `llms.txt`, `CLI_COMMAND_MATRIX.md`, strict-node core docs, default mdkg usage skills, `events.jsonl`, registry, and skill mirrors
+- run `mdkg index` after fresh init before treating `mdkg doctor --strict --json` as a clean health gate; init writes source scaffold files and index writes generated caches
 
 ### `mdkg upgrade`
 
@@ -145,6 +146,7 @@ Types:
 - `feat`
 - `task`
 - `bug`
+- `spike`
 - `checkpoint`
 - `test`
 
@@ -169,6 +171,16 @@ Agent workflow file type creation:
 Goal node creation:
 - `mdkg new goal "<title>" [options] [--json]`
 
+Spike node creation:
+- `mdkg new spike "<research question>" [options] [--json]`
+- spikes are actionable research/planning work nodes under `.mdkg/work/`
+- use `mdkg task start|update|done <spike-id>` for lifecycle state
+- spikes record research, sources, recommendations, follow-up node ideas, and
+  skill candidates in Markdown body sections
+- spikes do not perform web search, execute research, create follow-up nodes,
+  or generate `SKILL.md` files automatically
+- no `mdkg spike ...` namespace is exposed in this release
+
 Primary flags:
 - `--id <portable-id>` agent workflow file types only
 - `--ws <alias>`
@@ -500,7 +512,7 @@ Notes:
 - records include deterministic source metadata such as workspace, visibility, kind, id/qid/slug, path, headings, refs, source hash, and `indexed_at`
 - SPEC and WORK capability records include read-only `linkage` arrays for related SPECs, work contracts, work orders, and receipts when those graph mirrors exist
 - `.mdkg/index/capabilities.json` is rebuilt by `mdkg index` and by capability commands when stale
-- normal task, epic, feat, bug, test, and checkpoint nodes are intentionally excluded
+- normal task, epic, feat, bug, test, spike, and checkpoint nodes are intentionally excluded
 - visibility is mdkg export metadata used by capability filters, `pack --visibility`, public bundle checks, validation, and doctor diagnostics; it is not secret scanning or body redaction
 
 ### `mdkg spec`
@@ -745,7 +757,7 @@ Behavior:
 - `goal select` writes local ignored selected-goal state so `goal next` can omit the goal id.
 - `goal current` shows the selected goal or unique active goal fallback.
 - `goal clear` removes local selected-goal state.
-- `goal next` is read-only and selects feature, task, bug, or test work inside explicit `scope_refs`; epics are recursive containers, not executable returns.
+- `goal next` is read-only and selects feature, task, bug, test, or spike work inside explicit `scope_refs`; epics are recursive containers, not executable returns.
 - `goal claim` mutates only `active_node` after the work item is confirmed inside the goal scope.
 - `goal evaluate` is report-only and never runs commands from `required_checks`.
 - `goal pause`, `goal resume`, and `goal done` update `goal_state`, compatible work status, and `updated`.
@@ -779,7 +791,7 @@ Usage:
 - `mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"] [--json]`
 
 Behavior:
-- supports `task`, `bug`, and `test` only
+- supports task-like `feat`, `task`, `bug`, `test`, and `spike` nodes
 - sets `status: progress`
 - if `events.jsonl` is missing for the workspace, prints a short `stderr` reminder about `mdkg event enable`
 
@@ -795,7 +807,7 @@ Usage:
 - `                   [--clear-blocked-by] [--run-id <id>] [--note "<text>"] [--json]`
 
 Behavior:
-- supports `task`, `bug`, and `test` only
+- supports task-like `feat`, `task`, `bug`, `test`, and `spike` nodes
 - list mutations are additive and unique
 - scalar fields replace existing values
 - `--clear-blocked-by` clears blockers before optional re-add
@@ -810,7 +822,7 @@ Usage:
 - `                 [--add-refs <id,...>] [--checkpoint "<title>"] [--run-id <id>] [--note "<text>"] [--json]`
 
 Behavior:
-- supports `task`, `bug`, and `test` only
+- supports task-like `feat`, `task`, `bug`, `test`, and `spike` nodes
 - sets `status: done`
 - `--checkpoint` creates a related checkpoint
 - if `events.jsonl` is missing for the workspace, prints a short `stderr` reminder about `mdkg event enable`

package/README.md

@@ -14,7 +14,7 @@ mdkg stays deliberately boring:
 - first-class rebuildable SQLite cache through built-in `node:sqlite`
 - no daemon, hosted index, or vector DB
 
-Current package version in source: `0.2.0`
+Current package version in source: `0.3.1`
 
 mdkg is still pre-v1 public alpha software. The public package is usable, but graph, cache, bundle, and DAL contracts may continue to change quickly while the project converges on a stable v1 surface.
 
@@ -48,10 +48,16 @@ Initialize mdkg in a repo:
 
 ```bash
 mdkg init --agent
+mdkg index
 ```
 
 This is the canonical AI-agent bootstrap path. It creates `.mdkg/`, `AGENT_START.md`, `AGENTS.md`, `CLAUDE.md`, `llms.txt`, `CLI_COMMAND_MATRIX.md`, strict-node `SOUL.md` / `HUMAN.md`, the three default mdkg usage skills, `events.jsonl`, the skill registry, core pin updates, and mirrored skill folders under `.agents/skills/` and `.claude/skills/`. It also updates `.gitignore` / `.npmignore` by default. Use `--no-update-ignores` to opt out of those ignore-file updates.
 
+Run `mdkg index` after a fresh init before using `mdkg status --json` or
+`mdkg doctor --strict --json` as health gates. Init writes source scaffold
+files; indexing creates the generated graph, skill, capability, subgraph, and
+SQLite caches that strict doctor expects.
+
 For a non-agent markdown graph only, run `mdkg init`.
 
 Preview safe scaffold upgrades in an existing mdkg workspace:
@@ -86,7 +92,28 @@ mdkg goal next goal-1
 mdkg goal evaluate goal-1 --json
 ```
 
-Goal nodes capture a measurable end condition, recursive loop state, required skills, required checks, and completion evidence. They guide agent harnesses through repeated graph-backed progress, while tasks, bugs, tests, and features remain the concrete executable work units. In this release `mdkg goal evaluate` is report-only: it lists required checks and evidence state, but does not execute scripts.
+Goal nodes capture a measurable end condition, recursive loop state, required skills, required checks, and completion evidence. They guide agent harnesses through repeated graph-backed progress, while tasks, bugs, tests, spikes, and features remain the concrete executable work units. In this release `mdkg goal evaluate` is report-only: it lists required checks and evidence state, but does not execute scripts.
+
+Create a research spike when the next useful work is investigation, planning,
+or grounding a future implementation:
+
+```bash
+mdkg new spike "research mdkg.dev launch guide" --status todo --priority 1
+mdkg task start spike-1
+mdkg show spike-1
+```
+
+Spikes are task-like work nodes, not autonomous research agents. mdkg does not
+perform web search, execute research, create follow-up nodes, or generate
+`SKILL.md` files automatically. Record sources, findings, tradeoffs,
+recommendations, follow-up node ideas, and skill candidates in the spike body,
+then create follow-up work intentionally:
+
+```bash
+mdkg new task "write mdkg.dev quickstart guide" --parent spike-1 --status todo --priority 1
+mdkg new test "validate mdkg.dev docs examples" --parent spike-1 --status todo --priority 1
+mdkg new task "author mdkg.dev launch planning skill" --parent spike-1 --status todo --priority 2
+```
 
 Create an agent workflow document with a semantic portable id:
 
@@ -250,7 +277,7 @@ The root docs below are the canonical fast-start set for humans and agents:
 mdkg lives under a hidden root directory:
 - `.mdkg/core/` rules and pinned docs
 - `.mdkg/design/` product, design, and decision docs
-- `.mdkg/work/` tasks, bugs, tests, epics, checkpoints
+- `.mdkg/work/` tasks, bugs, tests, spikes, epics, checkpoints
 - `.mdkg/templates/` templates used by `mdkg new`
 - `.mdkg/skills/` Agent Skills packages
 - `.mdkg/archive/` sidecar metadata plus deterministic compressed source/artifact caches
@@ -434,12 +461,35 @@ as sealed state.
 
 Goal nodes are durable recursive objective contracts. Use `mdkg new goal "<objective>"` when a human or agent needs to keep working across multiple concrete nodes until a measurable end condition is achieved.
 
-`goal` is work-like but distinct from `task`: it can have status, priority, graph links, skills, explicit `scope_refs`, and structured goal fields, but normal `mdkg next` does not select goals. Use `mdkg goal select <goal-id>` once, then `mdkg goal next` to choose the next local feature, task, bug, or test inside that goal. `mdkg goal next <goal-id>` remains available for explicit selection. Epics organize goal scope recursively but are not returned as executable work.
+`goal` is work-like but distinct from `task`: it can have status, priority, graph links, skills, explicit `scope_refs`, and structured goal fields, but normal `mdkg next` does not select goals. Use `mdkg goal select <goal-id>` once, then `mdkg goal next` to choose the next local feature, task, bug, test, or spike inside that goal. `mdkg goal next <goal-id>` remains available for explicit selection. Epics organize goal scope recursively but are not returned as executable work.
 
 Use `mdkg goal claim [goal-id] <work-id>` to durably set `active_node` after choosing the next scoped item. `goal next` is read-only. Use `mdkg goal pause|resume|done` to update goal state after review.
 
 Required checks are stored as report-only guidance. Agents should run the checks themselves, record evidence in the goal or active work item, then use `mdkg goal evaluate` to summarize the current evidence state. During normal goal execution, skill improvements should be recorded as improvement candidates or proposal nodes; edit `SKILL.md` files only when the active node is explicit skill-maintenance work.
 
+## Research spikes
+
+Spikes are first-class actionable work nodes for research and planning. Use
+`mdkg new spike "<question>"` when the right output is a documented
+recommendation, not code. They share the existing task lifecycle:
+
+```bash
+mdkg new spike "research queue-backed materializer UX" --status todo --priority 1
+mdkg task start spike-1
+mdkg task update spike-1 --status review --add-refs task-250
+mdkg task done spike-1
+```
+
+The default spike template includes sections for research question, context,
+search plan, findings, options and tradeoffs, recommendation, follow-up nodes,
+skill candidates, data-structure and algorithm notes, UX notes, security notes,
+mdkg.dev launch implications, and evidence/sources.
+
+Spikes deliberately do not expose a `mdkg spike ...` namespace in this release,
+do not run browser or web-search tools, do not create tasks/tests/goals, and do
+not write `SKILL.md` files. They make the research output reviewable so humans
+or agents can intentionally create the next nodes with normal mdkg commands.
+
 ## Agent workflow files
 
 mdkg recognizes a small set of canonical agent workflow documents:

package/dist/cli.js

@@ -136,7 +136,7 @@ function printNewHelp(log) {
     log("Usage:");
     log('  mdkg new <type> "<title>" [options] [--json]');
     log("\nTypes:");
-    log("  rule prd edd dec prop goal epic feat task bug checkpoint test");
+    log("  rule prd edd dec prop goal epic feat task bug spike checkpoint test");
     log("\nAgent workflow file types:");
     log("  spec work work_order receipt feedback dispute proposal");
     log("  Use --id <portable-id> with these types for semantic ids like agent.image-worker.");
@@ -157,6 +157,9 @@ function printNewHelp(log) {
     log("  --owners <owner,owner,...> Owners");
     log("\nNotes:");
     log("  spec/work scaffold as validation-clean docs; relational workflow docs need real refs.");
+    log("  spike creates actionable research/planning work; use `mdkg task ...` for lifecycle.");
+    log("  record spike research evidence by editing the Markdown body sections.");
+    log("  spikes do not run web search, create follow-up nodes, generate SKILL.md, or expose `mdkg spike ...`.");
     printGlobalOptions(log);
 }
 function printGuideHelp(log) {
@@ -690,7 +693,7 @@ function printTaskHelp(log, subcommand) {
             log("Usage:");
             log('  mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"] [--json]');
             log("\nWhen to use:");
-            log("  Move a task, bug, or test into progress as a structured state change.");
+            log("  Move a task-like node (feat, task, bug, test, or spike) 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;
@@ -719,7 +722,8 @@ function printTaskHelp(log, subcommand) {
             log("  mdkg task update <id-or-qid> [options] [--json]");
             log('  mdkg task done <id-or-qid> [--checkpoint "<title>"] [options] [--json]');
             log("\nNotes:");
-            log("  `mdkg task ...` only supports feat, task, bug, and test nodes.");
+            log("  `mdkg task ...` only supports feat, task, bug, test, and spike nodes.");
+            log("  Spikes use this lifecycle; there is no separate `mdkg spike ...` command family.");
             log("  Feat and epic closeout remain checkpoint-first guidance plus manual parent updates.");
             printGlobalOptions(log);
     }
@@ -737,7 +741,7 @@ function printGoalHelp(log, subcommand) {
             log("Usage:");
             log("  mdkg goal next [goal-id-or-qid] [--ws <alias>] [--json]");
             log("\nWhen to use:");
-            log("  Select the next local feature, task, bug, or test inside a recursive goal without mutating active_node.");
+            log("  Select the next local feature, task, bug, test, or spike inside a recursive goal without mutating active_node.");
             log("  If no goal id is supplied, mdkg uses the selected goal or the unique active goal.");
             printGlobalOptions(log);
             return;
@@ -797,7 +801,7 @@ function printGoalHelp(log, subcommand) {
             log("  mdkg goal clear [--json]");
             log("  mdkg goal pause|resume|done <goal-id-or-qid> [--json]");
             log("\nNotes:");
-            log("  - goals orchestrate recursive progress; features, tasks, bugs, and tests are iterable work units");
+            log("  - goals orchestrate recursive progress; features, tasks, bugs, tests, and spikes are iterable work units");
             log("  - `mdkg goal next` is read-only; use `mdkg goal claim` to update active_node");
             log("  - goal evaluation is report-only and never executes required_checks");
             log("  - subgraph goal qids are read-only; update the source workspace instead");

package/dist/command-contract.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "package_version": "0.3.1",
+  "package_version": "0.3.2",
   "source": {
     "help_targets": "scripts/cli_help_targets.js",
     "command_matrix": "CLI_COMMAND_MATRIX.md"
@@ -7469,5 +7469,5 @@
       }
     }
   ],
-  "contract_hash": "5fa77fe079da6a7bd80fe4418133f204917f9157b600408c47f1e965610a5c72"
+  "contract_hash": "226793aa87d0fd57e187936a5ab17a86413149cbd2d52674324921b1e5051ff7"
 }

package/dist/commands/fix.js

@@ -288,7 +288,43 @@ function normalizeGraphRef(value, sourceWorkspace, knownWorkspaces, externalWork
 function frontmatterRefEntries(index, externalWorkspaces) {
     const knownWorkspaces = new Set(index.meta.workspaces);
     const entries = [];
+    const pushListEntries = (node, field, raw) => {
+        for (const [indexValue, value] of raw.entries()) {
+            const indexedField = `${field}[${indexValue}]`;
+            if (LOCAL_LIST_REF_FIELDS.has(field)) {
+                const target = normalizeGraphRef(value, node.ws, knownWorkspaces, externalWorkspaces);
+                if (target) {
+                    entries.push({
+                        qid: node.qid,
+                        path: node.path,
+                        field: indexedField,
+                        value,
+                        target,
+                        refKind: "graph",
+                        locationKind: "frontmatter",
+                    });
+                }
+            }
+            if (value.startsWith("archive://") && ARCHIVE_REF_LIST_FIELDS.has(field)) {
+                entries.push({
+                    qid: node.qid,
+                    path: node.path,
+                    field: indexedField,
+                    value,
+                    refKind: "archive",
+                    locationKind: "frontmatter",
+                });
+            }
+        }
+    };
     for (const node of Object.values(index.nodes).sort((a, b) => a.qid.localeCompare(b.qid))) {
+        for (const [field, raw] of [
+            ["links", node.links],
+            ["artifacts", node.artifacts],
+            ["refs", node.refs],
+        ]) {
+            pushListEntries(node, field, raw);
+        }
         for (const [field, raw] of Object.entries(node.attributes).sort(([a], [b]) => a.localeCompare(b))) {
             if (typeof raw === "string") {
                 if (LOCAL_SCALAR_REF_FIELDS.has(field)) {
@@ -320,33 +356,7 @@ function frontmatterRefEntries(index, externalWorkspaces) {
             if (!Array.isArray(raw)) {
                 continue;
             }
-            for (const [indexValue, value] of raw.entries()) {
-                const indexedField = `${field}[${indexValue}]`;
-                if (LOCAL_LIST_REF_FIELDS.has(field)) {
-                    const target = normalizeGraphRef(value, node.ws, knownWorkspaces, externalWorkspaces);
-                    if (target) {
-                        entries.push({
-                            qid: node.qid,
-                            path: node.path,
-                            field: indexedField,
-                            value,
-                            target,
-                            refKind: "graph",
-                            locationKind: "frontmatter",
-                        });
-                    }
-                }
-                if (value.startsWith("archive://") && ARCHIVE_REF_LIST_FIELDS.has(field)) {
-                    entries.push({
-                        qid: node.qid,
-                        path: node.path,
-                        field: indexedField,
-                        value,
-                        refKind: "archive",
-                        locationKind: "frontmatter",
-                    });
-                }
-            }
+            pushListEntries(node, field, raw);
         }
     }
     return entries;

package/dist/commands/goal.js

@@ -29,7 +29,7 @@ const qid_1 = require("../util/qid");
 const sort_1 = require("../util/sort");
 const event_support_1 = require("./event_support");
 const node_card_1 = require("./node_card");
-const CONCRETE_GOAL_NEXT_TYPES = new Set(["feat", "task", "bug", "test"]);
+const CONCRETE_GOAL_NEXT_TYPES = new Set(["feat", "task", "bug", "test", "spike"]);
 const SELECTED_GOAL_STATE_PATH = path_1.default.join(".mdkg", "state", "selected-goal.json");
 const GOAL_STATE_BY_ACTION = {
     pause: "paused",

package/dist/commands/next.js

@@ -7,8 +7,8 @@ const errors_1 = require("../util/errors");
 const qid_1 = require("../util/qid");
 const sort_1 = require("../util/sort");
 const node_card_1 = require("./node_card");
-const NEXT_TYPES = new Set(["feat", "task", "bug", "test"]);
-const NO_MATCH_MESSAGE = 'no matching work items found; consider `mdkg new task "..."` or `mdkg new test "..."`';
+const NEXT_TYPES = new Set(["feat", "task", "bug", "test", "spike"]);
+const NO_MATCH_MESSAGE = 'no matching work items found; consider `mdkg new task "..."`, `mdkg new test "..."`, or `mdkg new spike "..."`';
 function normalizeWorkspace(value) {
     if (!value || value === "all") {
         return undefined;

package/dist/commands/task.js

@@ -22,7 +22,7 @@ const atomic_1 = require("../util/atomic");
 const lock_1 = require("../util/lock");
 const event_support_1 = require("./event_support");
 const checkpoint_1 = require("./checkpoint");
-const MUTABLE_TASK_TYPES = new Set(["feat", "task", "bug", "test"]);
+const MUTABLE_TASK_TYPES = new Set(["feat", "task", "bug", "test", "spike"]);
 const SKILL_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 function parseCsvList(raw) {
     if (!raw) {
@@ -113,7 +113,7 @@ function loadMutableTaskNode(root, idOrQid, wsHint) {
         throw new errors_1.UsageError(`cannot mutate read-only subgraph node ${node.qid}; update the source workspace for subgraph ${node.source.subgraph_alias}`);
     }
     if (!MUTABLE_TASK_TYPES.has(node.type)) {
-        throw new errors_1.UsageError(`mdkg task only supports feat, task, bug, and test nodes; use markdown editing for ${node.type}:${node.id}`);
+        throw new errors_1.UsageError(`mdkg task only supports feat, task, bug, test, and spike nodes; use markdown editing for ${node.type}:${node.id}`);
     }
     const filePath = path_1.default.resolve(root, node.path);
     const content = fs_1.default.readFileSync(filePath, "utf8");

package/dist/commands/validate.js

@@ -36,6 +36,17 @@ const RECOMMENDED_HEADINGS = {
         "Links / Artifacts",
     ],
     feat: ["Overview", "Acceptance Criteria", "Notes"],
+    spike: [
+        "Research Question",
+        "Context And Constraints",
+        "Search Plan",
+        "Findings",
+        "Options And Tradeoffs",
+        "Recommendation",
+        "Follow-Up Nodes To Create",
+        "Skill Candidates",
+        "Evidence And Sources",
+    ],
     epic: ["Goal", "Scope", "Milestones", "Out of Scope", "Risks", "Links / Artifacts"],
     checkpoint: [
         "Summary",

package/dist/graph/goal_scope.js

@@ -5,7 +5,7 @@ exports.goalScopeRefs = goalScopeRefs;
 exports.collectGoalScope = collectGoalScope;
 const qid_1 = require("../util/qid");
 exports.GOAL_SCOPE_CONTAINER_TYPES = new Set(["epic", "feat"]);
-exports.GOAL_SCOPE_ACTIONABLE_TYPES = new Set(["feat", "task", "bug", "test"]);
+exports.GOAL_SCOPE_ACTIONABLE_TYPES = new Set(["feat", "task", "bug", "test", "spike"]);
 exports.GOAL_SCOPE_ALLOWED_TYPES = new Set([
     ...exports.GOAL_SCOPE_CONTAINER_TYPES,
     ...exports.GOAL_SCOPE_ACTIONABLE_TYPES,

package/dist/graph/node.js

@@ -10,7 +10,7 @@ const id_1 = require("../util/id");
 const refs_1 = require("../util/refs");
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const DEC_ID_RE = /^dec-[0-9]+$/;
-exports.WORK_TYPES = new Set(["goal", "epic", "feat", "task", "bug", "checkpoint", "test"]);
+exports.WORK_TYPES = new Set(["goal", "epic", "feat", "task", "bug", "spike", "checkpoint", "test"]);
 exports.DEC_TYPES = new Set(["dec"]);
 exports.ALLOWED_TYPES = new Set([
     "rule",
@@ -23,6 +23,7 @@ exports.ALLOWED_TYPES = new Set([
     "feat",
     "task",
     "bug",
+    "spike",
     "checkpoint",
     "test",
     "archive",

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -92,6 +92,7 @@ Validation commands:
 Node creation commands:
 - `mdkg new <type> "<title>" [options] [--json]`
 - `mdkg new goal "<title>" [options] [--json]`
+- `mdkg new spike "<research question>" [options] [--json]`
 
 Agent workflow file type creation:
 - `mdkg new spec "<title>" [options] [--json]`
@@ -109,6 +110,9 @@ Agent workflow notes:
 - `spec` and `work` scaffold as validation-clean standalone docs.
 - `work_order`, `receipt`, `feedback`, `dispute`, and `proposal` need real refs before strict `mdkg validate` passes.
 - `goal` nodes capture recursive objective state and required checks, but normal `mdkg next` does not select them.
+- `spike` nodes are actionable research/planning work under `.mdkg/work/`; use `mdkg task start|update|done` for lifecycle state.
+- Spikes record sources, findings, recommendations, follow-up node ideas, and skill candidates in Markdown body sections; they do not perform web search, execute research, create follow-up nodes, generate `SKILL.md`, or expose a `mdkg spike ...` namespace automatically.
+- after fresh init, run `mdkg index` before treating `mdkg doctor --strict --json` as a clean health gate; init writes source scaffold files and index writes generated caches.
 
 Workspace registry commands:
 - `mdkg workspace ls [--json]`
@@ -125,6 +129,7 @@ Task mutation commands:
 - `mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"] [--json]`
 - `mdkg task update <id-or-qid> [options] [--json]`
 - `mdkg task done <id-or-qid> [--checkpoint "<title>"] [options] [--json]`
+- task commands support task-like `feat`, `task`, `bug`, `test`, and `spike` nodes
 
 Checkpoint commands:
 - `mdkg checkpoint new <title> [--ws <alias>] [--json]`
@@ -157,7 +162,7 @@ Capability discovery:
 - capability records are deterministic cache projections from Markdown
 - records include source hash, headings, refs, and `indexed_at`
 - SPEC and WORK capability records include read-only `linkage` arrays for related SPECs, work contracts, work orders, and receipts when those graph mirrors exist
-- normal task, epic, feat, bug, test, and checkpoint nodes are intentionally excluded
+- normal task, epic, feat, bug, test, spike, and checkpoint nodes are intentionally excluded
 
 Spec capability records:
 - `mdkg spec list [--json]`
@@ -253,7 +258,7 @@ Goal nodes:
 - `mdkg goal pause <goal-id-or-qid> [--ws <alias>] [--json]`
 - `mdkg goal resume <goal-id-or-qid> [--ws <alias>] [--json]`
 - `mdkg goal done <goal-id-or-qid> [--ws <alias>] [--json]`
-- goals orchestrate recursive progress through explicit `scope_refs`; tasks, bugs, tests, and features remain concrete executable units
+- goals orchestrate recursive progress through explicit `scope_refs`; tasks, bugs, tests, spikes, and features remain concrete executable units
 - `goal next` is read-only; use `goal claim` to set `active_node`
 - `mdkg goal evaluate` is report-only and never runs commands from `required_checks`
 - skill improvements discovered during normal goal execution should be recorded as candidates or proposals unless the active node is skill-maintenance

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 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.
 
 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.2",
   "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": "c08de01602698af7eb46b70e9459df9c2fa6e6c32c06b2daab3f697baa450e0d"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/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",
@@ -256,7 +261,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "a9a7133e5a7c9a07a6814c679d04637370ea144eac19a6500980a37a2c4199f5"
+      "sha256": "888c5ce1372c0a7ba2c24bfe0aea97e221804cab1fa8940e06dc050330830a76"
     },
     {
       "path": "llms.txt",

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.2",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {
@@ -29,6 +29,7 @@
     "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: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 +40,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: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"
   },