mdkg 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -12,6 +12,87 @@ 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
+
+- 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`
@@ -723,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]`
@@ -739,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, 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`.
+- `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`
 
@@ -779,7 +797,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 +813,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 +828,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 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.
 
+## 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;
@@ -748,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]");
@@ -790,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, 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("  - `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);
@@ -2086,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");
@@ -2147,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.1",
+  "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": "5fa77fe079da6a7bd80fe4418133f204917f9157b600408c47f1e965610a5c72"
+  "contract_hash": "be42c29b89c1c3e3d059a8f9cbc564908d4dd694d848cf3d1b1800e8b30705e5"
 }