mdkg 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -12,6 +12,80 @@ mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL con
 
 - No changes yet.
 
+## 0.3.4 - 2026-06-17
+
+### Added
+
+- Added IDs-family repair apply support with `mdkg fix apply --family ids`
+  and the focused `mdkg fix ids [--apply]` convenience command.
+- Added `--base-ref` support for duplicate-ID repair planning so mainline IDs
+  can be preserved while incoming duplicate nodes receive the next unused
+  canonical numeric ID.
+- Added unresolved Git add/add conflict-stage repair for mdkg Markdown files:
+  stage 2 remains at the conflicted path, stage 3 is rewritten to a new
+  canonical ID/path, and the Git index conflict stages are resolved with a
+  receipt.
+- Added packed `smoke:id-repair` coverage that installs mdkg from a tarball in
+  a temp prefix, validates clean duplicate repair, base-ref link preservation,
+  unresolved Git conflict-stage repair, and final graph validation.
+
+### Changed
+
+- Updated `mdkg fix plan` receipts so duplicate-ID findings advertise
+  `apply_supported: true` with an explicit `apply_kind`, while index/cache and
+  graph-reference findings remain review-only.
+- Updated command help, README, init assets, command matrix, generated command
+  contract metadata, and publish-readiness assertions to document the new
+  IDs-only apply boundary.
+- Updated branch-conflict and fix-plan smokes to distinguish non-mutating plan
+  behavior from the newly apply-capable duplicate-ID repair family.
+
+### Security
+
+- `fix apply` refuses unsupported families, blocked plans, and non-IDs repair
+  findings instead of silently applying partial graph/reference/index repairs.
+- Duplicate-ID apply writes Markdown atomically under the mdkg mutation lock,
+  rebuilds derived indexes, and emits receipt evidence with touched paths,
+  source plan hash, and ambiguous reference notes.
+- Base-ref link rewriting is conservative: references in files absent from the
+  base ref can be rewritten to the repaired incoming ID, while base-existing
+  references remain on the mainline ID and ambiguous references are reported.
+
+## 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

@@ -1,7 +1,7 @@
 # CLI Command Matrix
 
 as_of: 2026-06-06
-package_version_in_source: 0.3.1
+package_version_in_source: 0.3.4
 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
 
@@ -61,7 +61,7 @@ Recursive long-running objective contracts are accessed through `mdkg goal ...`.
 Fresh init workspaces default to the SQLite access cache backend; existing migrated configs stay on JSON until opted in.
 Project application database foundation commands are accessed through `mdkg db ...`; `mdkg index` remains the compatibility shortcut for graph index rebuilds.
 Operator health summaries are accessed through read-only `mdkg status ...`; deeper diagnostics remain under `mdkg doctor ...`.
-Repair planning is accessed through read-only `mdkg fix plan ...`; apply behavior is intentionally deferred.
+Repair planning is accessed through read-only `mdkg fix plan ...`; duplicate-ID graph repairs can be applied through `mdkg fix apply --family ids ...` or the convenience `mdkg fix ids --apply ...`. Index/cache and graph-reference findings remain plan/manual-review only.
 
 ## Global usage
 
@@ -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`
 
@@ -1043,27 +1049,38 @@ JSON receipt shape:
 ### `mdkg fix`
 
 When to use:
-- plan reviewable graph/index repairs before any apply command exists
+- plan reviewable graph/index repairs before applying supported duplicate-ID rewrites
 - get a receipt-shaped JSON plan for automation and agent review
+- repair branch-merge duplicate IDs while preserving main/base IDs where possible
 
 Usage:
-- `mdkg fix plan [--family index|refs|ids|all] [--target <id-or-qid>] [--json]`
+- `mdkg fix plan [--family index|refs|ids|all] [--target <id-or-qid>] [--base-ref <ref>] [--json]`
+- `mdkg fix apply [--family ids] [--target <id-or-qid>] [--base-ref <ref>] [--json]`
+- `mdkg fix ids [--target <id-or-qid>] [--base-ref <ref>] [--apply] [--json]`
 
 Flags:
 - `--family <family>`
 - `--target <id-or-qid>`
+- `--base-ref <ref>`
+- `--apply`
 - `--json`
 
 Boundaries:
-- dry-run only and writes nothing
-- does not rebuild indexes, edit graph files, rename ids, or update references
-- `fix apply` is intentionally not available in the first repair-planning slice
+- `fix plan` is dry-run only and writes nothing
+- `fix apply` currently supports only IDs-family duplicate-ID graph rewrites
+- `fix ids` without `--apply` is equivalent to `fix plan --family ids`
+- `fix ids --apply` is equivalent to `fix apply --family ids`
+- apply rewrites graph Markdown atomically, rebuilds derived indexes, and emits a receipt
+- unresolved Git add/add conflict stages are handled by keeping stage 2 at the conflicted path and writing stage 3 to a new canonical ID/path
+- graph-reference and index/cache findings remain review-only guidance
 - initial families are index/cache, graph refs, and duplicate ids
 
 JSON receipt:
 - `{ action: "fix.plan", ok, schema_version, plan_id, plan_hash, generated_at, root, family, target, dirty, families, risk_counts, proposed_changes, blocked_changes, summary }`
-- each proposed change includes family, risk, status, reason, paths, refs, optional before/after values, command hint, and `apply_supported: false`
-- `summary.apply_deferred` remains true until a future apply design is approved
+- each proposed change includes family, risk, status, reason, paths, refs, optional before/after values, command hint, and `apply_supported`
+- duplicate-ID changes include candidate ID/path details and `apply_kind`
+- `{ action: "fix.apply", ok, schema_version, receipt_hash, root, family, target, base_ref, plan_id, plan_hash, applied_changes, touched_paths, ambiguous_reference_rewrites, index, summary }`
+- `summary.apply_deferred` remains true when the selected plan includes index/cache, graph-ref, blocked, or otherwise unsupported findings
 
 ### `mdkg doctor`
 

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.3.1`
+Current package version in source: `0.3.4`
 
 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.
 
@@ -341,9 +341,13 @@ warnings unless their underlying check fails.
 Use `mdkg fix plan --json` when you want repair guidance without mutation. It
 emits a receipt-shaped plan for generated index/cache repair, missing graph
 references, and duplicate local ids. Planned changes include affected paths,
-risk, reason codes, command hints, and `apply_supported: false`. `fix apply` is
-not exposed; apply behavior is deferred until the dry-run plan contract has
-enough evidence.
+risk, reason codes, command hints, and per-change `apply_supported` metadata.
+Duplicate-ID graph repairs can be applied with
+`mdkg fix apply --family ids --json` or `mdkg fix ids --apply --json`; use
+`--base-ref main` when mainline IDs should win. Index/cache and graph-reference
+findings remain review-only. For unresolved Git add/add conflicts, `fix ids`
+keeps stage 2 at the conflicted path, rewrites stage 3 to the next unused
+canonical ID/path, and records a receipt.
 
 ## Skills
 
@@ -461,9 +465,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);
@@ -869,24 +886,58 @@ function printFixHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "plan":
             log("Usage:");
-            log("  mdkg fix plan [--family index|refs|ids|all] [--target <id-or-qid>] [--json]");
+            log("  mdkg fix plan [--family index|refs|ids|all] [--target <id-or-qid>] [--base-ref <ref>] [--json]");
             log("\nBoundaries:");
             log("  - read-only repair planning; writes no files and does not rebuild indexes");
             log("  - emits a deterministic receipt-shaped JSON plan with paths, risks, and reason codes");
             log("  - initial families are index/cache, graph refs, and duplicate ids");
-            log("  - `fix apply` is intentionally not available in this release slice");
+            log("  - ids-family duplicate-id repairs can be applied with `mdkg fix apply --family ids`");
+            log("  - index/cache and graph-ref findings remain review-only guidance");
             log("\nOptions:");
             log("  --family <family>     Select index, refs, ids, or all (default all)");
             log("  --target <id-or-qid>  Optional node target for family planners");
+            log("  --base-ref <ref>      Prefer IDs that already exist at a Git base ref");
+            log("  --json                Emit machine-readable JSON output");
+            printGlobalOptions(log);
+            return;
+        case "apply":
+            log("Usage:");
+            log("  mdkg fix apply [--family ids] [--target <id-or-qid>] [--base-ref <ref>] [--json]");
+            log("\nBoundaries:");
+            log("  - applies only supported ids-family duplicate-ID rewrites");
+            log("  - refuses index/cache, graph-ref, all-family, blocked, and unsupported repairs");
+            log("  - writes graph Markdown atomically and rebuilds derived indexes");
+            log("  - emits a receipt with plan hash, touched paths, and manual-review reference notes");
+            log("\nOptions:");
+            log("  --family ids          Explicit apply family; ids is the only supported apply family");
+            log("  --target <id-or-qid>  Optional duplicate ID target");
+            log("  --base-ref <ref>      Prefer IDs that already exist at a Git base ref");
+            log("  --json                Emit machine-readable JSON output");
+            printGlobalOptions(log);
+            return;
+        case "ids":
+            log("Usage:");
+            log("  mdkg fix ids [--target <id-or-qid>] [--base-ref <ref>] [--apply] [--json]");
+            log("\nBoundaries:");
+            log("  - convenience command for duplicate-ID planning and application");
+            log("  - without --apply it is equivalent to `mdkg fix plan --family ids`");
+            log("  - with --apply it is equivalent to `mdkg fix apply --family ids`");
+            log("\nOptions:");
+            log("  --target <id-or-qid>  Optional duplicate ID target");
+            log("  --base-ref <ref>      Prefer IDs that already exist at a Git base ref");
+            log("  --apply               Apply supported duplicate-ID rewrites");
             log("  --json                Emit machine-readable JSON output");
             printGlobalOptions(log);
             return;
         default:
             log("Usage:");
-            log("  mdkg fix plan [--family index|refs|ids|all] [--target <id-or-qid>] [--json]");
+            log("  mdkg fix plan [--family index|refs|ids|all] [--target <id-or-qid>] [--base-ref <ref>] [--json]");
+            log("  mdkg fix apply [--family ids] [--target <id-or-qid>] [--base-ref <ref>] [--json]");
+            log("  mdkg fix ids [--target <id-or-qid>] [--base-ref <ref>] [--apply] [--json]");
             log("\nNotes:");
-            log("  - fix planning is dry-run only and writes nothing");
-            log("  - apply behavior is deferred until the receipt contract is proven");
+            log("  - fix plan is dry-run only and writes nothing");
+            log("  - fix apply is limited to duplicate-ID graph repairs with receipt evidence");
+            log("  - index/cache and graph-ref repairs remain plan/manual-review only");
             printGlobalOptions(log);
     }
 }
@@ -2090,6 +2141,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 +2210,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) {
@@ -2637,16 +2704,26 @@ function runCommand(parsed, root, runtime) {
             if (!sub) {
                 throw new errors_1.UsageError("fix requires a subcommand");
             }
-            if (sub !== "plan") {
+            if (!["plan", "apply", "ids"].includes(sub)) {
                 throw new errors_1.UsageError(`unknown fix subcommand: ${sub}`);
             }
             if (parsed.positionals.length > 2) {
-                throw new errors_1.UsageError("fix plan does not accept positional arguments");
+                throw new errors_1.UsageError(`fix ${sub} does not accept positional arguments`);
             }
             const family = requireFlagValue("--family", parsed.flags["--family"]);
             const target = requireFlagValue("--target", parsed.flags["--target"]);
+            const baseRef = requireFlagValue("--base-ref", parsed.flags["--base-ref"]);
             const json = parseBooleanFlag("--json", parsed.flags["--json"]);
-            (0, fix_1.runFixPlanCommand)({ root, family, target, json });
+            if (sub === "plan") {
+                (0, fix_1.runFixPlanCommand)({ root, family, target, baseRef, json });
+                return 0;
+            }
+            if (sub === "apply") {
+                (0, fix_1.runFixApplyCommand)({ root, family, target, baseRef, json });
+                return 0;
+            }
+            const apply = parseBooleanFlag("--apply", parsed.flags["--apply"]);
+            (0, fix_1.runFixIdsCommand)({ root, target, baseRef, json, apply });
             return 0;
         }
         case "format":