mdkg 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -12,6 +12,41 @@ mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL con
 
 - No changes yet.
 
+## 0.3.3 - 2026-06-16
+
+### Added
+
+- Added `mdkg goal activate <goal-id>` to make one local root goal active,
+  select it for goal routing, and pause competing active local root goals in the
+  same workspace.
+- Added goal-only archived lifecycle support with `mdkg goal archive`, allowing
+  historical roadmap goals to remain readable through show/list/search while
+  being excluded from actionable current/next routing.
+- Added parser and graph validation support for exactly one active local root
+  goal, while imported subgraph goals keep independent active-goal state in
+  their owning graphs.
+- Added packed `smoke:goal-lifecycle` prepublish coverage for goal activation,
+  archived-goal routing, archived discovery filters, strict doctor behavior, and
+  imported subgraph active-goal independence.
+
+### Changed
+
+- Updated README, init assets, agent startup guidance, command matrix, help
+  surfaces, generated command contract metadata, and publish-readiness assertions
+  to prefer `goal activate` for active goal selection.
+- Archived superseded local roadmap goals `goal-11`, `goal-12`, and `goal-15`
+  in this repository after replacement versioned goals were created.
+- Tightened the 0.3.3 graph hygiene path so the remaining release-candidate
+  sequence is smoke coverage followed by dry-run prepublish closeout.
+
+### Security
+
+- Archived goals are non-actionable historical context: they cannot be selected,
+  activated, claimed, resumed, or paused through the goal lifecycle surface.
+- `goal activate` keeps single-writer planning safer by pausing competing local
+  root goals instead of allowing multiple active local root goals to remain
+  silently actionable.
+
 ## 0.3.2 - 2026-06-16
 
 ### Added

package/CLI_COMMAND_MATRIX.md

@@ -735,14 +735,16 @@ When to use:
 Usage:
 - `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]`
@@ -751,27 +753,31 @@ Usage:
 - `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]`
+- `mdkg goal archive <goal-id-or-qid> [--ws <alias>] [--json]`
 
 Behavior:
 - `goal show` reports goal condition, goal state, scope refs, active node, required skills, required checks, and source path.
 - `goal select` writes local ignored selected-goal state so `goal next` can omit the goal id.
+- `goal activate` makes one local root goal active, pauses competing local active goals in the same workspace, and writes selected-goal state.
 - `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, 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`.
+- `goal archive` marks a superseded historical goal as `status: archived` and `goal_state: archived`; archived goals remain show/search/list readable but are excluded from active routing.
 - subgraph goal qids are read-only; update the source workspace instead.
 
 JSON receipts:
 - `show`: `{ action: "showed", goal }`
 - `select`: `{ action: "selected_goal", goal, selection }`
+- `activate`: `{ action: "activated", goal, activated_goal, paused_goals, selection, warnings }`
 - `current`: `{ action: "current", goal, source, warnings }`
 - `clear`: `{ action: "cleared_goal", path, cleared }`
 - `next`: `{ action: "selected", goal, goal_source, node, warnings }`
 - `claim`: `{ action: "claimed", goal, node }`
 - `evaluate`: `{ action: "evaluated", goal, report_only, runs_scripts, checks, completion_evidence_present }`
-- `pause|resume|done`: `{ action, goal }`
+- `pause|resume|done|archive`: `{ action, goal }`
 
 ### `mdkg task`
 

package/README.md

@@ -461,9 +461,9 @@ 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, 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.
+`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 activate <goal-id>` to make one local root goal active, pause competing local active goals, and select it for future `goal next` calls. Use `mdkg goal select <goal-id>` only when you want to change the local ignored selected-goal pointer without changing lifecycle state. `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.
+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, and `mdkg goal archive` for superseded historical roadmap goals that should remain readable but non-actionable.
 
 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.
 

package/dist/cli.js

@@ -752,6 +752,21 @@ function printGoalHelp(log, subcommand) {
             log("  Store a local selected goal so `mdkg goal next` can omit the goal id.");
             printGlobalOptions(log);
             return;
+        case "activate":
+            log("Usage:");
+            log("  mdkg goal activate <goal-id-or-qid> [--ws <alias>] [--json]");
+            log("\nWhen to use:");
+            log("  Make one local root goal active, pause competing local active goals, and select it for `goal next`.");
+            log("  Imported subgraph goals are read-only and are not mutated by activation.");
+            printGlobalOptions(log);
+            return;
+        case "archive":
+            log("Usage:");
+            log("  mdkg goal archive <goal-id-or-qid> [--ws <alias>] [--json]");
+            log("\nWhen to use:");
+            log("  Mark a superseded historical goal archived so it remains readable but is excluded from active routing.");
+            printGlobalOptions(log);
+            return;
         case "current":
             log("Usage:");
             log("  mdkg goal current [--ws <alias>] [--json]");
@@ -794,15 +809,17 @@ function printGoalHelp(log, subcommand) {
             log("Usage:");
             log("  mdkg goal show <goal-id-or-qid> [--json]");
             log("  mdkg goal select <goal-id-or-qid> [--json]");
+            log("  mdkg goal activate <goal-id-or-qid> [--json]");
             log("  mdkg goal current [--json]");
             log("  mdkg goal next [goal-id-or-qid] [--json]");
             log("  mdkg goal claim [goal-id-or-qid] <work-id-or-qid> [--json]");
             log("  mdkg goal evaluate <goal-id-or-qid> [--json]");
             log("  mdkg goal clear [--json]");
-            log("  mdkg goal pause|resume|done <goal-id-or-qid> [--json]");
+            log("  mdkg goal pause|resume|done|archive <goal-id-or-qid> [--json]");
             log("\nNotes:");
             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("  - `mdkg goal activate` enforces one active local root goal and pauses competing active goals");
             log("  - goal evaluation is report-only and never executes required_checks");
             log("  - subgraph goal qids are read-only; update the source workspace instead");
             printGlobalOptions(log);
@@ -2090,6 +2107,14 @@ function runGoalSubcommand(parsed, root) {
             (0, goal_1.runGoalSelectCommand)({ root, id, ws, json });
             return 0;
         }
+        case "activate": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("goal activate requires <goal-id-or-qid>");
+            }
+            (0, goal_1.runGoalActivateCommand)({ root, id, ws, json });
+            return 0;
+        }
         case "current":
             if (parsed.positionals.length > 2) {
                 throw new errors_1.UsageError("goal current does not accept positional arguments");
@@ -2151,8 +2176,16 @@ function runGoalSubcommand(parsed, root) {
             (0, goal_1.runGoalDoneCommand)({ root, id, ws, json });
             return 0;
         }
+        case "archive": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("goal archive requires <goal-id-or-qid>");
+            }
+            (0, goal_1.runGoalArchiveCommand)({ root, id, ws, json });
+            return 0;
+        }
         default:
-            throw new errors_1.UsageError("goal requires show/select/current/clear/next/claim/evaluate/pause/resume/done");
+            throw new errors_1.UsageError("goal requires show/select/activate/current/clear/next/claim/evaluate/pause/resume/done/archive");
     }
 }
 function runTaskSubcommand(parsed, root) {

package/dist/command-contract.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "package_version": "0.3.2",
+  "package_version": "0.3.3",
   "source": {
     "help_targets": "scripts/cli_help_targets.js",
     "command_matrix": "CLI_COMMAND_MATRIX.md"
@@ -2430,12 +2430,13 @@
       "usage": [
         "  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 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 clear [--json]",
-        "  mdkg goal pause|resume|done <goal-id-or-qid> [--json]"
+        "  mdkg goal pause|resume|done|archive <goal-id-or-qid> [--json]"
       ],
       "args": [
         {
@@ -2505,7 +2506,7 @@
         }
       ],
       "examples": [
-        "  mdkg goal current [--json]",
+        "  mdkg goal activate <goal-id-or-qid> [--json]",
         "  mdkg goal select <goal-id-or-qid> [--json]",
         "  mdkg goal show <goal-id-or-qid> [--json]"
       ],
@@ -2514,6 +2515,172 @@
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
+    {
+      "key": "goal activate",
+      "path": [
+        "goal",
+        "activate"
+      ],
+      "category": "goal",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg goal activate command",
+      "usage": [
+        "  mdkg goal activate <goal-id-or-qid> [--ws <alias>] [--json]"
+      ],
+      "args": [
+        {
+          "name": "goal-id-or-qid",
+          "required": true,
+          "source": "<goal-id-or-qid>"
+        }
+      ],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "activate-goal-and-pause-competing-goals"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [
+        ".mdkg/**/*.md",
+        ".mdkg/index/**"
+      ],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "mutation-lock-required",
+      "atomic_write_policy": "atomic-file-writes",
+      "receipts": [
+        "goal-state-receipt"
+      ],
+      "danger_level": "moderate",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg goal activate <goal-id-or-qid> [--ws <alias>] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help goal activate",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "goal archive",
+      "path": [
+        "goal",
+        "archive"
+      ],
+      "category": "goal",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg goal archive command",
+      "usage": [
+        "  mdkg goal archive <goal-id-or-qid> [--ws <alias>] [--json]"
+      ],
+      "args": [
+        {
+          "name": "goal-id-or-qid",
+          "required": true,
+          "source": "<goal-id-or-qid>"
+        }
+      ],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.command_output.v1",
+      "side_effects": [
+        "archive-goal"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [
+        ".mdkg/**/*.md",
+        ".mdkg/index/**"
+      ],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "mutation-lock-required",
+      "atomic_write_policy": "atomic-file-writes",
+      "receipts": [
+        "goal-state-receipt"
+      ],
+      "danger_level": "moderate",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg goal archive <goal-id-or-qid> [--ws <alias>] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help goal archive",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
     {
       "key": "goal claim",
       "path": [
@@ -7469,5 +7636,5 @@
       }
     }
   ],
-  "contract_hash": "226793aa87d0fd57e187936a5ab17a86413149cbd2d52674324921b1e5051ff7"
+  "contract_hash": "be42c29b89c1c3e3d059a8f9cbc564908d4dd694d848cf3d1b1800e8b30705e5"
 }

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");
@@ -35,11 +37,13 @@ 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/graph/node.js

@@ -30,7 +30,7 @@ exports.ALLOWED_TYPES = new Set([
     ...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",
@@ -280,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

@@ -242,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]`
@@ -258,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]`
+- `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

package/dist/init/README.md

@@ -35,7 +35,7 @@ mdkg fix plan --json
 mdkg validate
 ```
 
-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.
+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

package/dist/init/init-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.3.2",
+  "mdkg_version": "0.3.3",
   "files": [
     {
       "path": ".mdkg/config.json",
@@ -61,7 +61,7 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "c08de01602698af7eb46b70e9459df9c2fa6e6c32c06b2daab3f697baa450e0d"
+      "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",
@@ -246,7 +246,7 @@
     {
       "path": "AGENT_START.md",
       "category": "startup_doc",
-      "sha256": "cf58e37c72be2593f1d920520dbdc6e316182bfda5c49837443a8b18024504c7"
+      "sha256": "46e734b6eae92eb957c3e29fb4d206e4be3fd6d32dd00e888e01a0dc75979428"
     },
     {
       "path": "AGENTS.md",
@@ -261,7 +261,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "888c5ce1372c0a7ba2c24bfe0aea97e221804cab1fa8940e06dc050330830a76"
+      "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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdkg",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {
@@ -30,6 +30,7 @@
     "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",
@@ -40,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: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",
+    "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"
   },