mdkg 0.3.1 → 0.3.3

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

@@ -7,12 +7,14 @@ exports.runGoalShowCommand = runGoalShowCommand;
 exports.runGoalEvaluateCommand = runGoalEvaluateCommand;
 exports.runGoalNextCommand = runGoalNextCommand;
 exports.runGoalSelectCommand = runGoalSelectCommand;
+exports.runGoalActivateCommand = runGoalActivateCommand;
 exports.runGoalCurrentCommand = runGoalCurrentCommand;
 exports.runGoalClearCommand = runGoalClearCommand;
 exports.runGoalClaimCommand = runGoalClaimCommand;
 exports.runGoalPauseCommand = runGoalPauseCommand;
 exports.runGoalResumeCommand = runGoalResumeCommand;
 exports.runGoalDoneCommand = runGoalDoneCommand;
+exports.runGoalArchiveCommand = runGoalArchiveCommand;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const config_1 = require("../core/config");
@@ -29,17 +31,19 @@ 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",
     resume: "active",
     done: "achieved",
+    archive: "archived",
 };
 const STATUS_BY_ACTION = {
     pause: "blocked",
     resume: "progress",
     done: "done",
+    archive: "archived",
 };
 function normalizeWorkspace(value) {
     if (!value) {
@@ -95,6 +99,22 @@ function writeSelectedGoalState(root, node, now) {
     };
     (0, atomic_1.atomicWriteFile)(selectedGoalPath(root), `${JSON.stringify(state, null, 2)}\n`);
 }
+function readNodeFrontmatter(root, node) {
+    const filePath = path_1.default.resolve(root, node.path);
+    const parsed = (0, frontmatter_1.parseFrontmatter)(fs_1.default.readFileSync(filePath, "utf8"), filePath);
+    return {
+        filePath,
+        frontmatter: { ...parsed.frontmatter },
+        body: parsed.body,
+    };
+}
+function writeNodeFrontmatterFile(filePath, frontmatter, body, now) {
+    frontmatter.updated = (0, date_1.formatDate)(now);
+    const lines = (0, frontmatter_1.formatFrontmatter)(frontmatter, frontmatter_1.DEFAULT_FRONTMATTER_KEY_ORDER);
+    const frontmatterBlock = ["---", ...lines, "---"].join("\n");
+    const content = body.length > 0 ? `${frontmatterBlock}\n${body}` : frontmatterBlock;
+    (0, atomic_1.atomicWriteFile)(filePath, content);
+}
 function removeSelectedGoalState(root) {
     const filePath = selectedGoalPath(root);
     if (!fs_1.default.existsSync(filePath)) {
@@ -125,6 +145,14 @@ function activeGoalCandidates(index, wsHint) {
         .filter((node) => node.status === "progress" && node.attributes.goal_state === "active")
         .sort((a, b) => a.qid.localeCompare(b.qid));
 }
+function activeGoalConflicts(index, target) {
+    return activeGoalCandidates(index, target.ws).filter((node) => node.qid !== target.qid);
+}
+function isArchivedGoal(node) {
+    return Boolean(node &&
+        node.type === "goal" &&
+        (node.status === "archived" || node.attributes.goal_state === "archived"));
+}
 function resolveGoalSelection(root, index, idOrQid, wsHint) {
     const warnings = [];
     if (idOrQid) {
@@ -137,19 +165,24 @@ function resolveGoalSelection(root, index, idOrQid, wsHint) {
     const selected = readSelectedGoalState(root, warnings);
     if (selected) {
         const node = index.nodes[selected.qid];
-        if (node && node.type === "goal" && !node.source?.imported) {
+        if (node && node.type === "goal" && !node.source?.imported && !isArchivedGoal(node)) {
             return { node, source: "selected", warnings };
         }
-        warnings.push(`selected goal ${selected.qid} is not available; run \`mdkg goal select <goal-id>\``);
+        if (isArchivedGoal(node)) {
+            warnings.push(`selected goal ${selected.qid} is archived; run \`mdkg goal activate <goal-id>\` or \`mdkg goal clear\``);
+        }
+        else {
+            warnings.push(`selected goal ${selected.qid} is not available; run \`mdkg goal select <goal-id>\``);
+        }
     }
     const active = activeGoalCandidates(index, wsHint);
     if (active.length === 1) {
         return { node: active[0], source: "unique_active", warnings };
     }
     if (active.length > 1) {
-        throw new errors_1.UsageError(`multiple active goals found: ${active.map((node) => node.qid).join(", ")}; run \`mdkg goal select <goal-id>\``);
+        throw new errors_1.UsageError(`multiple active goals found: ${active.map((node) => node.qid).join(", ")}; run \`mdkg goal activate <goal-id>\``);
     }
-    throw new errors_1.NotFoundError("no selected goal or unique active goal found; run `mdkg goal select <goal-id>`");
+    throw new errors_1.NotFoundError("no selected goal or unique active goal found; run `mdkg goal activate <goal-id>`");
 }
 function loadGoal(root, idOrQid, wsHint) {
     const config = (0, config_1.loadConfig)(root);
@@ -201,11 +234,7 @@ function goalReceipt(root, loaded) {
     };
 }
 function writeGoalFile(loaded, now) {
-    loaded.frontmatter.updated = (0, date_1.formatDate)(now);
-    const lines = (0, frontmatter_1.formatFrontmatter)(loaded.frontmatter, frontmatter_1.DEFAULT_FRONTMATTER_KEY_ORDER);
-    const frontmatterBlock = ["---", ...lines, "---"].join("\n");
-    const content = loaded.body.length > 0 ? `${frontmatterBlock}\n${loaded.body}` : frontmatterBlock;
-    (0, atomic_1.atomicWriteFile)(loaded.filePath, content);
+    writeNodeFrontmatterFile(loaded.filePath, loaded.frontmatter, loaded.body, now);
 }
 function maybeReindex(root, config) {
     if (!config.index.auto_reindex) {
@@ -215,6 +244,9 @@ function maybeReindex(root, config) {
 }
 function ensureStatusAllowed(config, status) {
     const normalized = status.toLowerCase();
+    if (normalized === "archived") {
+        return normalized;
+    }
     const allowed = new Set(config.work.status_enum.map((value) => value.toLowerCase()));
     if (!allowed.has(normalized)) {
         throw new errors_1.UsageError(`goal status ${normalized} is not allowed by work.status_enum`);
@@ -301,6 +333,24 @@ function runGoalEvaluateCommand(options) {
 }
 function runGoalNextCommand(options) {
     const loaded = loadGoal(options.root, options.id, options.ws);
+    if (isArchivedGoal(loaded.node)) {
+        const warnings = [...loaded.warnings, `${loaded.node.qid} is archived and has no actionable next work`];
+        if (options.json) {
+            console.log(JSON.stringify({
+                action: "selected",
+                goal: goalReceipt(options.root, loaded),
+                goal_source: loaded.resolutionSource,
+                node: null,
+                warnings,
+            }, null, 2));
+            return;
+        }
+        for (const warning of warnings) {
+            console.error(`warning: ${warning}`);
+        }
+        console.error("no actionable local work found for goal");
+        return;
+    }
     const statusPreference = loaded.config.work.next.status_preference.map((status) => status.toLowerCase());
     const statusRanks = new Set(statusPreference);
     const warnings = [...loaded.warnings];
@@ -362,6 +412,9 @@ function runGoalSelectCommand(options) {
     const config = (0, config_1.loadConfig)(options.root);
     return (0, lock_1.withMutationLock)(options.root, config.index.lock_timeout_ms, () => {
         const loaded = loadGoal(options.root, options.id, options.ws);
+        if (isArchivedGoal(loaded.node)) {
+            throw new errors_1.UsageError(`cannot select archived goal ${loaded.node.qid}`);
+        }
         const now = options.now ?? new Date();
         writeSelectedGoalState(options.root, loaded.node, now);
         const receipt = {
@@ -379,6 +432,74 @@ function runGoalSelectCommand(options) {
         console.log(`selected goal: ${loaded.node.qid}`);
     });
 }
+function runGoalActivateCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    return (0, lock_1.withMutationLock)(options.root, config.index.lock_timeout_ms, () => {
+        const loaded = loadGoal(options.root, options.id, options.ws);
+        const currentState = String(loaded.frontmatter.goal_state ?? "");
+        const currentStatus = String(loaded.frontmatter.status ?? "");
+        if (loaded.node.status === "done" || currentStatus === "done" || currentState === "achieved") {
+            throw new errors_1.UsageError(`cannot activate achieved goal ${loaded.node.qid}`);
+        }
+        if (loaded.node.status === "archived" || currentStatus === "archived" || currentState === "archived") {
+            throw new errors_1.UsageError(`cannot activate archived goal ${loaded.node.qid}`);
+        }
+        const now = options.now ?? new Date();
+        const pausedGoals = [];
+        const conflicts = activeGoalConflicts(loaded.index, loaded.node);
+        for (const conflict of conflicts) {
+            const conflictFile = readNodeFrontmatter(options.root, conflict);
+            conflictFile.frontmatter.goal_state = "paused";
+            conflictFile.frontmatter.status = ensureStatusAllowed(config, "blocked");
+            writeNodeFrontmatterFile(conflictFile.filePath, conflictFile.frontmatter, conflictFile.body, now);
+            pausedGoals.push({
+                workspace: conflict.ws,
+                id: conflict.id,
+                qid: conflict.qid,
+                path: conflict.path,
+                previous_status: conflict.status ?? "",
+                previous_goal_state: String(conflict.attributes.goal_state ?? ""),
+                status: "blocked",
+                goal_state: "paused",
+            });
+        }
+        loaded.frontmatter.goal_state = "active";
+        loaded.frontmatter.status = ensureStatusAllowed(config, "progress");
+        writeGoalFile(loaded, now);
+        writeSelectedGoalState(options.root, loaded.node, now);
+        maybeReindex(options.root, loaded.config);
+        (0, event_support_1.appendAutomaticEvent)({
+            root: options.root,
+            ws: loaded.node.ws,
+            kind: "GOAL_ACTIVATE",
+            status: "ok",
+            refs: [loaded.node.id, ...conflicts.map((node) => node.id)],
+            notes: `goal activate via mdkg goal activate`,
+            now,
+        });
+        const receipt = {
+            action: "activated",
+            goal: goalReceipt(options.root, loaded),
+            activated_goal: goalReceipt(options.root, loaded),
+            paused_goals: pausedGoals,
+            selection: {
+                path: SELECTED_GOAL_STATE_PATH,
+                selected_at: now.toISOString(),
+            },
+            warnings: conflicts.length > 0
+                ? [`paused ${conflicts.length} competing active goal(s) in workspace ${loaded.node.ws}`]
+                : [],
+        };
+        if (options.json) {
+            console.log(JSON.stringify(receipt, null, 2));
+            return;
+        }
+        for (const warning of receipt.warnings) {
+            console.error(`warning: ${warning}`);
+        }
+        console.log(`goal activate: ${loaded.node.qid}`);
+    });
+}
 function runGoalCurrentCommand(options) {
     const config = (0, config_1.loadConfig)(options.root);
     const { index } = (0, index_cache_1.loadIndex)({ root: options.root, config });
@@ -389,12 +510,17 @@ function runGoalCurrentCommand(options) {
     const selected = readSelectedGoalState(options.root, warnings);
     if (selected) {
         const selectedNode = index.nodes[selected.qid];
-        if (selectedNode && selectedNode.type === "goal" && !selectedNode.source?.imported) {
+        if (selectedNode && selectedNode.type === "goal" && !selectedNode.source?.imported && !isArchivedGoal(selectedNode)) {
             node = selectedNode;
             source = "selected";
         }
         else {
-            warnings.push(`selected goal ${selected.qid} is not available; run \`mdkg goal select <goal-id>\``);
+            if (isArchivedGoal(selectedNode)) {
+                warnings.push(`selected goal ${selected.qid} is archived; run \`mdkg goal activate <goal-id>\` or \`mdkg goal clear\``);
+            }
+            else {
+                warnings.push(`selected goal ${selected.qid} is not available; run \`mdkg goal select <goal-id>\``);
+            }
         }
     }
     if (!node) {
@@ -405,7 +531,7 @@ function runGoalCurrentCommand(options) {
         }
         else if (active.length > 1) {
             source = "ambiguous";
-            warnings.push(`multiple active goals found: ${active.map((goal) => goal.qid).join(", ")}`);
+            warnings.push(`multiple active goals found: ${active.map((goal) => goal.qid).join(", ")}; run \`mdkg goal activate <goal-id>\``);
         }
     }
     const receipt = {
@@ -464,6 +590,9 @@ function runGoalClaimCommand(options) {
     const config = (0, config_1.loadConfig)(options.root);
     return (0, lock_1.withMutationLock)(options.root, config.index.lock_timeout_ms, () => {
         const loaded = loadGoal(options.root, options.id, options.ws);
+        if (isArchivedGoal(loaded.node)) {
+            throw new errors_1.UsageError(`cannot claim work for archived goal ${loaded.node.qid}`);
+        }
         const resolved = (0, qid_1.resolveQid)(loaded.index, options.workId, loaded.node.ws);
         if (resolved.status !== "ok") {
             throw new errors_1.NotFoundError((0, qid_1.formatResolveError)("work", options.workId, resolved, loaded.node.ws));
@@ -510,6 +639,9 @@ function runGoalClaimCommand(options) {
 }
 function runGoalStateMutationLocked(action, options) {
     const loaded = loadGoal(options.root, options.id, options.ws);
+    if (action !== "archive" && isArchivedGoal(loaded.node)) {
+        throw new errors_1.UsageError(`cannot ${action} archived goal ${loaded.node.qid}`);
+    }
     const now = options.now ?? new Date();
     loaded.frontmatter.goal_state = GOAL_STATE_BY_ACTION[action];
     loaded.frontmatter.status = ensureStatusAllowed(loaded.config, STATUS_BY_ACTION[action]);
@@ -546,3 +678,7 @@ function runGoalDoneCommand(options) {
     const config = (0, config_1.loadConfig)(options.root);
     return (0, lock_1.withMutationLock)(options.root, config.index.lock_timeout_ms, () => runGoalStateMutationLocked("done", options));
 }
+function runGoalArchiveCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    return (0, lock_1.withMutationLock)(options.root, config.index.lock_timeout_ms, () => runGoalStateMutationLocked("archive", options));
+}

package/dist/commands/new.js

@@ -228,11 +228,12 @@ function runNewCommandLocked(options) {
     let status;
     if (node_1.WORK_TYPES.has(type)) {
         const allowed = new Set(config.work.status_enum.map((value) => value.toLowerCase()));
+        const allowedForType = type === "goal" ? new Set([...allowed, "archived"]) : allowed;
         status = statusInput ?? (type === "goal" && allowed.has("progress")
             ? "progress"
             : config.work.status_enum[0]?.toLowerCase());
-        if (!status || !allowed.has(status)) {
-            throw new errors_1.UsageError(`--status must be one of ${Array.from(allowed).join(", ")}`);
+        if (!status || !allowedForType.has(status)) {
+            throw new errors_1.UsageError(`--status must be one of ${Array.from(allowedForType).join(", ")}`);
         }
     }
     else if (type === "dec") {
@@ -346,7 +347,7 @@ function runNewCommandLocked(options) {
         skills: skills.length > 0 ? skills : undefined,
         cases: cases.length > 0 ? cases : undefined,
         supersedes: options.supersedes ? options.supersedes.toLowerCase() : undefined,
-        goal_state: type === "goal" ? (status === "done" ? "achieved" : status === "blocked" ? "blocked" : "active") : undefined,
+        goal_state: type === "goal" ? (status === "done" ? "achieved" : status === "blocked" ? "blocked" : status === "archived" ? "archived" : "active") : undefined,
         goal_condition: type === "goal" ? title : undefined,
         max_iterations: type === "goal" ? 25 : undefined,
         blocked_after_attempts: type === "goal" ? 3 : undefined,

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,13 +23,14 @@ exports.ALLOWED_TYPES = new Set([
     "feat",
     "task",
     "bug",
+    "spike",
     "checkpoint",
     "test",
     "archive",
     ...agent_file_types_1.AGENT_FILE_TYPES,
 ]);
 const DEC_STATUS = new Set(["proposed", "accepted", "rejected", "superseded"]);
-const GOAL_STATE = new Set(["active", "paused", "achieved", "blocked", "budget_limited"]);
+const GOAL_STATE = new Set(["active", "paused", "achieved", "blocked", "budget_limited", "archived"]);
 const SKILL_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const GOAL_ATTRIBUTE_KEYS = [
     "goal_state",
@@ -279,13 +280,14 @@ function parseNode(content, filePath, options) {
     const statusValue = optionalString(frontmatter, "status", filePath);
     let status = undefined;
     const workStatus = new Set(options.workStatusEnum.map((value) => value.toLowerCase()));
+    const allowedWorkStatus = type === "goal" ? new Set([...workStatus, "archived"]) : workStatus;
     if (exports.WORK_TYPES.has(type)) {
         if (!statusValue) {
             throw formatError(filePath, "status is required for work items");
         }
         const normalized = requireLowercase(statusValue, "status", filePath);
-        if (!workStatus.has(normalized)) {
-            throw formatError(filePath, `status must be one of ${Array.from(workStatus).join(", ")}`);
+        if (!allowedWorkStatus.has(normalized)) {
+            throw formatError(filePath, `status must be one of ${Array.from(allowedWorkStatus).join(", ")}`);
         }
         status = normalized;
     }

package/dist/graph/validate_graph.js

@@ -485,6 +485,26 @@ function validateGoalRefs(index, allowMissing, errors) {
         }
     }
 }
+function validateSingleActiveRootGoals(index, errors) {
+    const activeByWorkspace = {};
+    for (const [qid, node] of Object.entries(index.nodes)) {
+        if (node.type !== "goal" || node.source?.imported) {
+            continue;
+        }
+        if (node.status === "progress" && node.attributes.goal_state === "active") {
+            if (!activeByWorkspace[node.ws]) {
+                activeByWorkspace[node.ws] = [];
+            }
+            activeByWorkspace[node.ws].push(qid);
+        }
+    }
+    for (const [workspace, qids] of Object.entries(activeByWorkspace)) {
+        if (qids.length <= 1) {
+            continue;
+        }
+        pushError(errors, `${workspace}: multiple active root goals found: ${qids.sort().join(", ")}; run mdkg goal activate <goal-id> to select exactly one`);
+    }
+}
 function detectPrevNextCycles(index, errors) {
     const nodes = index.nodes;
     const seen = new Set();
@@ -533,6 +553,7 @@ function collectGraphErrors(index, options = {}) {
     validateAgentWorkflowFeedbackProposalRefs(index, allowMissing, knownSkillSlugs, externalWorkspaces, errors);
     validateArchiveUriRefs(index, allowMissing, errors);
     validateGoalRefs(index, allowMissing, errors);
+    validateSingleActiveRootGoals(index, errors);
     detectPrevNextCycles(index, errors);
     return errors;
 }

package/dist/init/AGENT_START.md

@@ -24,7 +24,7 @@ Agent operating prompt:
 - Use `mdkg show <id>` for direct inspection and `mdkg show <id> --meta` for card-only inspection.
 - Use `mdkg search "..."` and `mdkg next` to discover current work.
 - Use `mdkg new goal "..."` for long-running recursive objectives that need an explicit end condition, active node, required skills, required checks, and completion evidence.
-- Use `mdkg goal select <goal-id>` when a goal is active, then `mdkg goal next` to surface one scoped feature, task, bug, or test at a time; normal `mdkg next` remains for non-goal concrete work.
+- Use `mdkg goal activate <goal-id>` to make one local root goal active, then `mdkg goal next` to surface one scoped feature, task, bug, test, or spike at a time; normal `mdkg next` remains for non-goal concrete work.
 - Use `mdkg goal claim [goal-id] <work-id>` only after accepting the surfaced work item; `mdkg goal next` is read-only.
 - Treat goal `required_checks` as report-only guidance from mdkg. Run commands yourself, then record evidence in the goal or active work item.
 - Record skill improvement candidates during normal goal execution; edit `SKILL.md` only when the active node is explicit skill-maintenance work.
@@ -78,7 +78,7 @@ If the active task is known:
 - `mdkg validate`
 
 If an active goal is known:
-- `mdkg goal select <goal-id>`
+- `mdkg goal activate <goal-id>`
 - `mdkg goal current`
 - `mdkg goal next`
 - `mdkg goal claim <work-id>`

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]`
@@ -237,14 +242,16 @@ Work semantic mirrors:
 Goal nodes:
 - `mdkg goal show <goal-id-or-qid> [--json]`
 - `mdkg goal select <goal-id-or-qid> [--json]`
+- `mdkg goal activate <goal-id-or-qid> [--json]`
 - `mdkg goal current [--json]`
 - `mdkg goal clear [--json]`
 - `mdkg goal next [goal-id-or-qid] [--json]`
 - `mdkg goal claim [goal-id-or-qid] <work-id-or-qid> [--json]`
 - `mdkg goal evaluate <goal-id-or-qid> [--json]`
-- `mdkg goal pause|resume|done <goal-id-or-qid> [--json]`
+- `mdkg goal pause|resume|done|archive <goal-id-or-qid> [--json]`
 - `mdkg goal show <goal-id-or-qid> [--ws <alias>] [--json]`
 - `mdkg goal select <goal-id-or-qid> [--ws <alias>] [--json]`
+- `mdkg goal activate <goal-id-or-qid> [--ws <alias>] [--json]`
 - `mdkg goal current [--ws <alias>] [--json]`
 - `mdkg goal next [goal-id-or-qid] [--ws <alias>] [--json]`
 - `mdkg goal claim <work-id-or-qid> [--ws <alias>] [--json]`
@@ -253,7 +260,10 @@ 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
+- `mdkg goal archive <goal-id-or-qid> [--ws <alias>] [--json]`
+- goals orchestrate recursive progress through explicit `scope_refs`; tasks, bugs, tests, spikes, and features remain concrete executable units
+- `goal activate` makes one local root goal active, pauses competing local active goals in the same workspace, and writes selected-goal state
+- `goal archive` marks a superseded historical goal archived so it remains readable but not actionable
 - `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