mdkg 0.3.3 → 0.3.4

package/CHANGELOG.md

@@ -12,6 +12,45 @@ 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

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
 
@@ -1049,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
 

package/dist/cli.js

@@ -886,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);
     }
 }
@@ -2670,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":

package/dist/command-contract.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "package_version": "0.3.3",
+  "package_version": "0.3.4",
   "source": {
     "help_targets": "scripts/cli_help_targets.js",
     "command_matrix": "CLI_COMMAND_MATRIX.md"
@@ -2050,7 +2050,9 @@
       "visibility": "public",
       "summary": "mdkg fix command",
       "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]"
       ],
       "args": [],
       "flags": [
@@ -2104,13 +2106,232 @@
         }
       ],
       "examples": [
-        "  mdkg fix plan [--family index|refs|ids|all] [--target <id-or-qid>] [--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]",
+        "  mdkg fix plan [--family index|refs|ids|all] [--target <id-or-qid>] [--base-ref <ref>] [--json]"
       ],
       "docs": {
         "help_target": "mdkg help fix",
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
+    {
+      "key": "fix apply",
+      "path": [
+        "fix",
+        "apply"
+      ],
+      "category": "fix",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg fix apply command",
+      "usage": [
+        "  mdkg fix apply [--family ids] [--target <id-or-qid>] [--base-ref <ref>] [--json]"
+      ],
+      "args": [],
+      "flags": [
+        {
+          "name": "--base-ref",
+          "value": "<ref>",
+          "required": false,
+          "description": "--base-ref <ref>      Prefer IDs that already exist at a Git base ref"
+        },
+        {
+          "name": "--family",
+          "value": "ids",
+          "required": false,
+          "description": "--family ids          Explicit apply family; ids is the only supported apply family"
+        },
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--json",
+          "value": null,
+          "required": false,
+          "description": "--json                Emit machine-readable JSON output"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--target",
+          "value": "<id-or-qid>",
+          "required": false,
+          "description": "--target <id-or-qid>  Optional duplicate ID target"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.fix_apply.v1",
+      "side_effects": [
+        "rebuild-derived-indexes",
+        "rewrite-duplicate-node-ids"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [
+        ".mdkg/**/*.md",
+        ".mdkg/index/**"
+      ],
+      "dry_run": {
+        "supported": false,
+        "apply_supported": true,
+        "apply_family": "ids"
+      },
+      "lock_policy": "mutation-lock-required",
+      "atomic_write_policy": "atomic-file-writes",
+      "receipts": [
+        "fix-apply-receipt"
+      ],
+      "danger_level": "high",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg fix apply [--family ids] [--target <id-or-qid>] [--base-ref <ref>] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help fix apply",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "fix ids",
+      "path": [
+        "fix",
+        "ids"
+      ],
+      "category": "fix",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg fix ids command",
+      "usage": [
+        "  mdkg fix ids [--target <id-or-qid>] [--base-ref <ref>] [--apply] [--json]"
+      ],
+      "args": [],
+      "flags": [
+        {
+          "name": "--apply",
+          "value": "it",
+          "required": false,
+          "description": "- without --apply it is equivalent to `mdkg fix plan --family ids`"
+        },
+        {
+          "name": "--base-ref",
+          "value": "<ref>",
+          "required": false,
+          "description": "--base-ref <ref>      Prefer IDs that already exist at a Git base ref"
+        },
+        {
+          "name": "--family",
+          "value": "ids`",
+          "required": false,
+          "description": "- without --apply it is equivalent to `mdkg fix plan --family ids`"
+        },
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--json",
+          "value": null,
+          "required": false,
+          "description": "--json                Emit machine-readable JSON output"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "--root, -r <path>   Run against a specific repo root"
+        },
+        {
+          "name": "--target",
+          "value": "<id-or-qid>",
+          "required": false,
+          "description": "--target <id-or-qid>  Optional duplicate ID target"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text",
+        "json"
+      ],
+      "json_schema_ref": "mdkg.fix_ids.v1",
+      "side_effects": [
+        "plan-or-rewrite-duplicate-node-ids",
+        "rebuild-derived-indexes-when-apply"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [
+        ".mdkg/**/*.md",
+        ".mdkg/index/**"
+      ],
+      "dry_run": {
+        "supported": true,
+        "default": true,
+        "apply_flag": "--apply",
+        "apply_supported": true,
+        "apply_family": "ids"
+      },
+      "lock_policy": "mutation-lock-required-when-apply",
+      "atomic_write_policy": "atomic-file-writes-when-apply",
+      "receipts": [
+        "fix-apply-receipt",
+        "fix-plan-receipt"
+      ],
+      "danger_level": "high",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg fix ids [--target <id-or-qid>] [--base-ref <ref>] [--apply] [--json]"
+      ],
+      "docs": {
+        "help_target": "mdkg help fix ids",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
     {
       "key": "fix plan",
       "path": [
@@ -2122,15 +2343,21 @@
       "visibility": "public",
       "summary": "mdkg fix plan command",
       "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]"
       ],
       "args": [],
       "flags": [
+        {
+          "name": "--base-ref",
+          "value": "<ref>",
+          "required": false,
+          "description": "--base-ref <ref>      Prefer IDs that already exist at a Git base ref"
+        },
         {
           "name": "--family",
-          "value": "<family>",
+          "value": "ids`",
           "required": false,
-          "description": "--family <family>     Select index, refs, ids, or all (default all)"
+          "description": "- ids-family duplicate-id repairs can be applied with `mdkg fix apply --family ids`"
         },
         {
           "name": "--help",
@@ -2178,7 +2405,8 @@
       "dry_run": {
         "supported": true,
         "default": true,
-        "apply_supported": false
+        "apply_supported": true,
+        "apply_family": "ids"
       },
       "lock_policy": "none-read-only",
       "atomic_write_policy": "none-read-only",
@@ -2198,7 +2426,7 @@
         }
       ],
       "examples": [
-        "  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]"
       ],
       "docs": {
         "help_target": "mdkg help fix plan",
@@ -7636,5 +7864,5 @@
       }
     }
   ],
-  "contract_hash": "be42c29b89c1c3e3d059a8f9cbc564908d4dd694d848cf3d1b1800e8b30705e5"
+  "contract_hash": "a2e027cdfdb590f3882cb824b9c8b1cf153e39ba63738ab0fad2d92277794325"
 }

package/dist/commands/fix.js

@@ -4,7 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.collectFixPlan = collectFixPlan;
+exports.collectFixApply = collectFixApply;
 exports.runFixPlanCommand = runFixPlanCommand;
+exports.runFixApplyCommand = runFixApplyCommand;
+exports.runFixIdsCommand = runFixIdsCommand;
 const crypto_1 = __importDefault(require("crypto"));
 const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
@@ -23,6 +26,9 @@ const template_schema_1 = require("../graph/template_schema");
 const workspace_files_1 = require("../graph/workspace_files");
 const errors_1 = require("../util/errors");
 const refs_1 = require("../util/refs");
+const atomic_1 = require("../util/atomic");
+const lock_1 = require("../util/lock");
+const index_1 = require("./index");
 const FAMILY_VALUES = new Set(["index", "refs", "ids", "all"]);
 const CONCRETE_FAMILIES = ["index", "refs", "ids"];
 function stableValue(value) {
@@ -668,14 +674,143 @@ function planRefRepairs(root, target) {
     return { proposed: changes, blocked: [] };
 }
 function candidateDuplicateId(baseId, used) {
-    for (let index = 2;; index += 1) {
-        const candidate = `${baseId}-dup-${index}`;
+    const match = /^([a-z]+)-([0-9]+)$/.exec(baseId);
+    if (!match) {
+        throw new errors_1.UsageError(`duplicate id ${baseId} cannot be repaired automatically because it is not a canonical numeric id`);
+    }
+    const prefix = match[1];
+    const start = Number.parseInt(match[2], 10) + 1;
+    for (let index = start;; index += 1) {
+        const candidate = `${prefix}-${index}`;
         if (!used.has(candidate)) {
             used.add(candidate);
             return candidate;
         }
     }
 }
+function gitShow(root, refPath) {
+    const result = (0, child_process_1.spawnSync)("git", ["show", refPath], { cwd: root, encoding: "utf8" });
+    if (result.status !== 0) {
+        return undefined;
+    }
+    return result.stdout;
+}
+function runGitStrict(root, args) {
+    const result = (0, child_process_1.spawnSync)("git", args, { cwd: root, encoding: "utf8" });
+    if (result.status !== 0) {
+        throw new errors_1.UsageError(`git ${args.join(" ")} failed: ${(result.stderr || result.stdout).trim() || "unknown error"}`);
+    }
+}
+function baseRefIdPaths(root, baseRef, files, config) {
+    const pathsById = new Map();
+    if (!baseRef) {
+        return pathsById;
+    }
+    const templateSchemas = (0, template_schema_1.loadTemplateSchemas)(root, config, node_1.ALLOWED_TYPES);
+    for (const absPath of files) {
+        const relativePath = rel(root, absPath);
+        const content = gitShow(root, `${baseRef}:${relativePath}`);
+        if (content === undefined) {
+            continue;
+        }
+        try {
+            const node = (0, node_1.parseNode)(content, absPath, {
+                workStatusEnum: config.work.status_enum,
+                priorityMin: config.work.priority_min,
+                priorityMax: config.work.priority_max,
+                templateSchemas,
+            });
+            if (!pathsById.has(node.id)) {
+                pathsById.set(node.id, new Set());
+            }
+            pathsById.get(node.id)?.add(relativePath);
+        }
+        catch {
+            continue;
+        }
+    }
+    return pathsById;
+}
+function rewriteIdInNodeContent(content, fromId, toId) {
+    const lines = content.split(/\n/);
+    let inFrontmatter = false;
+    let frontmatterClosed = false;
+    let idRewritten = false;
+    const rewritten = lines.map((line, index) => {
+        if (index === 0 && line.trim() === "---") {
+            inFrontmatter = true;
+            return line;
+        }
+        if (inFrontmatter && !frontmatterClosed && line.trim() === "---") {
+            frontmatterClosed = true;
+            inFrontmatter = false;
+            return line;
+        }
+        if (inFrontmatter && !idRewritten && line === `id: ${fromId}`) {
+            idRewritten = true;
+            return `id: ${toId}`;
+        }
+        return line.split(fromId).join(toId);
+    });
+    if (!idRewritten) {
+        throw new errors_1.UsageError(`unable to rewrite id ${fromId}; frontmatter id line not found`);
+    }
+    return rewritten.join("\n");
+}
+function isInsideRoot(root, filePath) {
+    const realRoot = `${relativeRoot(root)}${path_1.default.sep}`;
+    return path_1.default.resolve(filePath).startsWith(realRoot);
+}
+function replaceIdInRelativePath(relativePath, fromId, toId, usedPaths) {
+    const parsed = path_1.default.posix.parse(relativePath);
+    const baseName = parsed.base.includes(fromId)
+        ? parsed.base.replace(fromId, toId)
+        : `${toId}-${parsed.base}`;
+    let candidate = path_1.default.posix.join(parsed.dir, baseName);
+    if (!usedPaths.has(candidate)) {
+        usedPaths.add(candidate);
+        return candidate;
+    }
+    for (let index = 2;; index += 1) {
+        const suffixed = path_1.default.posix.join(parsed.dir, `${parsed.name}-${toId}-${index}${parsed.ext}`);
+        if (!usedPaths.has(suffixed)) {
+            usedPaths.add(suffixed);
+            return suffixed;
+        }
+    }
+}
+function gitConflictStages(root) {
+    const output = runGit(root, ["ls-files", "-u", "--", ".mdkg"]) ?? "";
+    const groups = new Map();
+    for (const line of output.split(/\r?\n/).filter(Boolean)) {
+        const match = /^([0-7]+) ([0-9a-f]+) ([123])\t(.+)$/.exec(line);
+        if (!match || !match[4].endsWith(".md")) {
+            continue;
+        }
+        const entry = {
+            mode: match[1],
+            object: match[2],
+            stage: Number.parseInt(match[3], 10),
+            path: match[4],
+        };
+        groups.set(entry.path, [...(groups.get(entry.path) ?? []), entry]);
+    }
+    return groups;
+}
+function workspaceAliasForPath(root, config, relativePath) {
+    const absPath = path_1.default.resolve(root, relativePath);
+    for (const alias of Object.keys(config.workspaces).sort()) {
+        const entry = config.workspaces[alias];
+        if (!entry.enabled) {
+            continue;
+        }
+        const wsRoot = path_1.default.resolve(root, entry.path, entry.mdkg_dir);
+        if (absPath === wsRoot || absPath.startsWith(`${wsRoot}${path_1.default.sep}`)) {
+            return alias;
+        }
+    }
+    return undefined;
+}
 function filesContaining(root, files, needle) {
     return files
         .filter((filePath) => {
@@ -728,18 +863,118 @@ function referenceRewriteItems(root, files, from, to) {
         .filter((item) => Boolean(item))
         .sort((a, b) => a.path.localeCompare(b.path));
 }
-function planDuplicateIdRepairs(root, target) {
+function planGitStageDuplicateIdRepairs(root, target, config, usedIdsByAlias, usedPaths, startIndex) {
+    const templateSchemas = (0, template_schema_1.loadTemplateSchemas)(root, config, node_1.ALLOWED_TYPES);
+    const proposed = [];
+    let matchedTarget = false;
+    for (const [relativePath, stages] of [...gitConflictStages(root).entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        const ours = stages.find((entry) => entry.stage === 2);
+        const theirs = stages.find((entry) => entry.stage === 3);
+        if (!ours || !theirs) {
+            continue;
+        }
+        const alias = workspaceAliasForPath(root, config, relativePath);
+        if (!alias) {
+            continue;
+        }
+        const oursContent = gitShow(root, `:2:${relativePath}`);
+        const theirsContent = gitShow(root, `:3:${relativePath}`);
+        if (oursContent === undefined || theirsContent === undefined) {
+            continue;
+        }
+        try {
+            const absPath = path_1.default.resolve(root, relativePath);
+            const oursNode = (0, node_1.parseNode)(oursContent, absPath, {
+                workStatusEnum: config.work.status_enum,
+                priorityMin: config.work.priority_min,
+                priorityMax: config.work.priority_max,
+                templateSchemas,
+            });
+            const theirsNode = (0, node_1.parseNode)(theirsContent, absPath, {
+                workStatusEnum: config.work.status_enum,
+                priorityMin: config.work.priority_min,
+                priorityMax: config.work.priority_max,
+                templateSchemas,
+            });
+            if (oursNode.id !== theirsNode.id) {
+                continue;
+            }
+            const duplicateId = oursNode.id;
+            const qid = `${alias}:${duplicateId}`;
+            const targetMatches = !target || target.toLowerCase() === duplicateId || target.toLowerCase() === qid || target === relativePath;
+            if (!targetMatches) {
+                continue;
+            }
+            matchedTarget = true;
+            const usedIds = usedIdsByAlias.get(alias) ?? new Set();
+            usedIds.add(oursNode.id);
+            usedIds.add(theirsNode.id);
+            usedIdsByAlias.set(alias, usedIds);
+            const candidate = candidateDuplicateId(duplicateId, usedIds);
+            const candidatePath = replaceIdInRelativePath(relativePath, duplicateId, candidate, usedPaths);
+            proposed.push({
+                id: `ids.${String(startIndex + proposed.length + 1).padStart(3, "0")}`,
+                family: "ids",
+                risk: "high",
+                status: "planned",
+                reason: "git_stage_duplicate_id",
+                paths: [relativePath, candidatePath],
+                refs: [qid, `${alias}:${candidate}`].sort(),
+                evidence: {
+                    conflict_kind: "git_index_unresolved_duplicate_id",
+                    workspace: alias,
+                    duplicate_id: duplicateId,
+                    conflict_path: relativePath,
+                    canonical_stage: 2,
+                    duplicate_stage: 3,
+                    current_blob: ours.object,
+                    incoming_blob: theirs.object,
+                    deterministic_rule: "keep stage 2 at the conflicted path, rewrite stage 3 to the next unused canonical numeric id and path, then git add both files",
+                },
+                before: {
+                    duplicate_id: duplicateId,
+                    workspace: alias,
+                    conflict_path: relativePath,
+                    canonical_stage: 2,
+                    duplicate_stage: 3,
+                    current_blob: ours.object,
+                    incoming_blob: theirs.object,
+                },
+                after: {
+                    candidate_id: candidate,
+                    candidate_qid: `${alias}:${candidate}`,
+                    candidate_path: candidatePath,
+                    canonical_path: relativePath,
+                    collision_free: true,
+                    deterministic_rule: "keep stage 2 at the conflicted path, rewrite stage 3 to the next unused canonical numeric id and path, then git add both files",
+                },
+                command_hint: `mdkg fix ids --target ${duplicateId} --apply --json`,
+                apply_supported: true,
+                apply_kind: "git_stage_duplicate_id_rewrite",
+            });
+        }
+        catch {
+            continue;
+        }
+    }
+    return { proposed, matchedTarget };
+}
+function planDuplicateIdRepairs(root, target, baseRef) {
     const config = (0, config_1.loadConfig)(root);
     const templateSchemas = (0, template_schema_1.loadTemplateSchemas)(root, config, node_1.ALLOWED_TYPES);
     const docsByAlias = (0, workspace_files_1.listWorkspaceDocFilesByAlias)(root, config);
     const proposed = [];
     const blocked = [];
+    const usedIdsByAlias = new Map();
+    const usedPaths = new Set();
     let matchedTarget = !target;
     for (const alias of Object.keys(docsByAlias).sort()) {
         const records = [];
         const usedIds = new Set();
         const files = docsByAlias[alias].sort();
+        const basePathsById = baseRefIdPaths(root, baseRef, files, config);
         for (const filePath of files) {
+            usedPaths.add(rel(root, filePath));
             if (path_1.default.basename(filePath) === "core.md" && path_1.default.basename(path_1.default.dirname(filePath)) === "core") {
                 continue;
             }
@@ -762,6 +997,7 @@ function planDuplicateIdRepairs(root, target) {
                 continue;
             }
         }
+        usedIdsByAlias.set(alias, usedIds);
         const groups = new Map();
         for (const record of records) {
             groups.set(record.id, [...(groups.get(record.id) ?? []), record]);
@@ -778,18 +1014,29 @@ function planDuplicateIdRepairs(root, target) {
                 continue;
             }
             matchedTarget = true;
-            const canonical = group[0];
+            const basePaths = basePathsById.get(id);
+            const baseCanonical = basePaths ? group.find((record) => basePaths.has(record.path)) : undefined;
+            const canonical = baseCanonical ?? group[0];
             const referencePaths = filesContaining(root, files, id);
-            const duplicateRecords = group.slice(1);
+            const duplicateRecords = group.filter((record) => record.path !== canonical.path);
             const groupPaths = group.map((record) => record.path).sort();
-            const deterministicRule = "keep the lexicographically first path unchanged; propose <id>-dup-<n> for each later path";
+            const deterministicRule = baseCanonical
+                ? "keep the path that already existed at --base-ref unchanged; propose the next unused canonical numeric id for each other path"
+                : "keep the lexicographically first path unchanged; propose the next unused canonical numeric id for each later path";
             for (const duplicate of duplicateRecords) {
                 const candidate = candidateDuplicateId(id, usedIds);
+                const selfReferenceRewrites = referenceRewriteItems(root, [duplicate.absPath], id, candidate);
+                const externalReferenceRewrites = referenceRewriteItems(root, files.filter((filePath) => filePath !== duplicate.absPath), id, candidate);
+                const safeReferenceRewrites = baseRef
+                    ? externalReferenceRewrites.filter((item) => gitShow(root, `${baseRef}:${item.path}`) === undefined)
+                    : [];
+                const safeReferencePaths = new Set(safeReferenceRewrites.map((item) => item.path));
+                const ambiguousReferenceRewrites = externalReferenceRewrites.filter((item) => !safeReferencePaths.has(item.path));
                 proposed.push({
                     id: `ids.${String(proposed.length + 1).padStart(3, "0")}`,
                     family: "ids",
                     risk: "high",
-                    status: "manual_review",
+                    status: "planned",
                     reason: "duplicate_id",
                     paths: [duplicate.path],
                     refs: Array.from(new Set([canonical.qid, duplicate.qid])).sort(),
@@ -797,6 +1044,8 @@ function planDuplicateIdRepairs(root, target) {
                         conflict_kind: "duplicate_local_id",
                         branch_merge_suspected: true,
                         workspace: alias,
+                        base_ref: baseRef ?? null,
+                        base_ref_canonical: Boolean(baseCanonical),
                         duplicate_id: id,
                         group_size: group.length,
                         group_paths: groupPaths,
@@ -813,6 +1062,7 @@ function planDuplicateIdRepairs(root, target) {
                     before: {
                         duplicate_id: id,
                         workspace: alias,
+                        base_ref: baseRef ?? null,
                         canonical_path: canonical.path,
                         duplicate_path: duplicate.path,
                         duplicate_group: {
@@ -827,14 +1077,23 @@ function planDuplicateIdRepairs(root, target) {
                         collision_free: true,
                         deterministic_rule: deterministicRule,
                         reference_paths: referencePaths,
-                        reference_rewrite_plan: referenceRewriteItems(root, files, id, candidate),
+                        self_reference_rewrites: selfReferenceRewrites,
+                        safe_reference_rewrites: safeReferenceRewrites,
+                        ambiguous_reference_rewrites: ambiguousReferenceRewrites,
+                        reference_rewrite_plan: [...selfReferenceRewrites, ...safeReferenceRewrites, ...ambiguousReferenceRewrites].sort((a, b) => a.path.localeCompare(b.path)),
                     },
-                    command_hint: `review ${duplicate.path} and update id ${id} to ${candidate}`,
-                    apply_supported: false,
+                    command_hint: `mdkg fix apply --family ids --target ${id}${baseRef ? ` --base-ref ${baseRef}` : ""} --json`,
+                    apply_supported: true,
+                    apply_kind: "duplicate_id_rewrite",
                 });
             }
         }
     }
+    const stageRepairs = planGitStageDuplicateIdRepairs(root, target, config, usedIdsByAlias, usedPaths, proposed.length);
+    proposed.push(...stageRepairs.proposed);
+    if (stageRepairs.matchedTarget) {
+        matchedTarget = true;
+    }
     if (!matchedTarget && target) {
         blocked.push({
             id: "ids.target.001",
@@ -881,15 +1140,20 @@ function collectFixPlan(options) {
     const root = relativeRoot(options.root);
     const indexRepairs = selected.includes("index") ? planIndexRepairs(root) : { proposed: [], blocked: [] };
     const refRepairs = selected.includes("refs") ? planRefRepairs(root, options.target) : { proposed: [], blocked: [] };
-    const idRepairs = selected.includes("ids") ? planDuplicateIdRepairs(root, options.target) : { proposed: [], blocked: [] };
+    const idRepairs = selected.includes("ids")
+        ? planDuplicateIdRepairs(root, options.target, options.baseRef)
+        : { proposed: [], blocked: [] };
     const proposedChanges = sortChanges([...indexRepairs.proposed, ...refRepairs.proposed, ...idRepairs.proposed]);
     const blockedChanges = sortChanges([...indexRepairs.blocked, ...refRepairs.blocked, ...idRepairs.blocked]);
+    const supportedApplyCount = proposedChanges.filter((change) => change.apply_supported).length;
+    const unsupportedApplyCount = proposedChanges.filter((change) => !change.apply_supported).length;
     const body = {
         action: "fix.plan",
         schema_version: 1,
         root,
         family,
         target: options.target ?? null,
+        base_ref: options.baseRef ?? null,
         dirty: collectDirtyState(root),
         families: emptyFamilySummaries(selected).map((entry) => ({
             ...entry,
@@ -903,9 +1167,13 @@ function collectFixPlan(options) {
             selected_families: selected,
             proposed_count: proposedChanges.length,
             blocked_count: blockedChanges.length,
-            apply_supported: false,
-            apply_deferred: true,
-            message: "fix apply is not available; this command is review-only and writes no files",
+            apply_supported: supportedApplyCount > 0,
+            apply_deferred: unsupportedApplyCount > 0 || blockedChanges.length > 0,
+            supported_apply_count: supportedApplyCount,
+            unsupported_apply_count: unsupportedApplyCount,
+            message: supportedApplyCount > 0
+                ? "ids-family duplicate-id repairs can be applied with mdkg fix apply --family ids or mdkg fix ids --apply"
+                : "this command is review-only for the selected findings and writes no files",
         },
     };
     const planHash = sha256(body);
@@ -917,6 +1185,171 @@ function collectFixPlan(options) {
         plan_id: `fix-plan-${planHash.slice("sha256:".length, "sha256:".length + 16)}`,
     };
 }
+function normalizeApplyFamily(value) {
+    const family = normalizeFamily(value ?? "ids");
+    if (family !== "ids") {
+        throw new errors_1.UsageError("fix apply currently supports only --family ids");
+    }
+    return "ids";
+}
+function applyDuplicateIdChange(root, change) {
+    if (change.family !== "ids" || change.reason !== "duplicate_id" || change.apply_kind !== "duplicate_id_rewrite") {
+        throw new errors_1.UsageError(`unsupported fix apply change ${change.id}`);
+    }
+    const relativePath = change.paths[0];
+    if (!relativePath) {
+        throw new errors_1.UsageError(`fix apply change ${change.id} is missing a path`);
+    }
+    const absPath = path_1.default.resolve(root, relativePath);
+    if (!isInsideRoot(root, absPath)) {
+        throw new errors_1.UsageError(`fix apply refused path outside repo: ${relativePath}`);
+    }
+    const before = change.before;
+    const after = change.after;
+    const fromId = typeof before.duplicate_id === "string" ? before.duplicate_id : undefined;
+    const toId = typeof after.candidate_id === "string" ? after.candidate_id : undefined;
+    if (!fromId || !toId) {
+        throw new errors_1.UsageError(`fix apply change ${change.id} is missing duplicate id rewrite details`);
+    }
+    const current = fs_1.default.readFileSync(absPath, "utf8");
+    const rewritten = rewriteIdInNodeContent(current, fromId, toId);
+    if (rewritten === current) {
+        throw new errors_1.UsageError(`fix apply change ${change.id} produced no file changes`);
+    }
+    (0, atomic_1.atomicWriteFile)(absPath, rewritten);
+    const afterDetails = change.after;
+    const safeReferenceRewrites = Array.isArray(afterDetails.safe_reference_rewrites)
+        ? afterDetails.safe_reference_rewrites
+        : [];
+    const touchedPaths = new Set([relativePath]);
+    for (const rewrite of safeReferenceRewrites) {
+        if (typeof rewrite.path !== "string" || typeof rewrite.from !== "string" || typeof rewrite.to !== "string") {
+            continue;
+        }
+        const rewriteAbs = path_1.default.resolve(root, rewrite.path);
+        if (!isInsideRoot(root, rewriteAbs) || !fs_1.default.existsSync(rewriteAbs)) {
+            continue;
+        }
+        const rewriteCurrent = fs_1.default.readFileSync(rewriteAbs, "utf8");
+        const rewriteNext = rewriteCurrent.split(rewrite.from).join(rewrite.to);
+        if (rewriteNext !== rewriteCurrent) {
+            (0, atomic_1.atomicWriteFile)(rewriteAbs, rewriteNext);
+            touchedPaths.add(rewrite.path);
+        }
+    }
+    return {
+        id: change.id,
+        family: "ids",
+        reason: change.reason,
+        apply_kind: "duplicate_id_rewrite",
+        path: relativePath,
+        touched_paths: Array.from(touchedPaths).sort(),
+        refs: change.refs,
+        before: change.before,
+        after: change.after,
+    };
+}
+function applyGitStageDuplicateIdChange(root, change) {
+    if (change.family !== "ids" || change.reason !== "git_stage_duplicate_id" || change.apply_kind !== "git_stage_duplicate_id_rewrite") {
+        throw new errors_1.UsageError(`unsupported git-stage fix apply change ${change.id}`);
+    }
+    const before = change.before;
+    const after = change.after;
+    const fromId = typeof before.duplicate_id === "string" ? before.duplicate_id : undefined;
+    const conflictPath = typeof before.conflict_path === "string" ? before.conflict_path : undefined;
+    const candidateId = typeof after.candidate_id === "string" ? after.candidate_id : undefined;
+    const candidatePath = typeof after.candidate_path === "string" ? after.candidate_path : undefined;
+    if (!fromId || !conflictPath || !candidateId || !candidatePath) {
+        throw new errors_1.UsageError(`fix apply change ${change.id} is missing git-stage rewrite details`);
+    }
+    const canonicalContent = gitShow(root, `:2:${conflictPath}`);
+    const duplicateContent = gitShow(root, `:3:${conflictPath}`);
+    if (canonicalContent === undefined || duplicateContent === undefined) {
+        throw new errors_1.UsageError(`fix apply change ${change.id} could not read Git conflict stages for ${conflictPath}`);
+    }
+    const canonicalAbs = path_1.default.resolve(root, conflictPath);
+    const candidateAbs = path_1.default.resolve(root, candidatePath);
+    if (!isInsideRoot(root, canonicalAbs) || !isInsideRoot(root, candidateAbs)) {
+        throw new errors_1.UsageError(`fix apply refused path outside repo while resolving ${conflictPath}`);
+    }
+    const rewrittenDuplicate = rewriteIdInNodeContent(duplicateContent, fromId, candidateId);
+    (0, atomic_1.atomicWriteFile)(canonicalAbs, canonicalContent);
+    (0, atomic_1.atomicWriteFile)(candidateAbs, rewrittenDuplicate);
+    runGitStrict(root, ["add", "--", conflictPath, candidatePath]);
+    return {
+        id: change.id,
+        family: "ids",
+        reason: change.reason,
+        apply_kind: "git_stage_duplicate_id_rewrite",
+        path: conflictPath,
+        touched_paths: [conflictPath, candidatePath],
+        refs: change.refs,
+        before: change.before,
+        after: change.after,
+    };
+}
+function collectFixApply(options) {
+    const family = normalizeApplyFamily(options.family);
+    const root = relativeRoot(options.root);
+    const config = (0, config_1.loadConfig)(root);
+    return (0, lock_1.withMutationLock)(root, config.index.lock_timeout_ms, () => {
+        const plan = collectFixPlan({ ...options, root, family });
+        const applicable = plan.proposed_changes.filter((change) => change.apply_supported);
+        const unsupported = plan.proposed_changes.filter((change) => !change.apply_supported);
+        if (plan.blocked_changes.length > 0) {
+            throw new errors_1.UsageError("fix apply refused because the plan contains blocked changes");
+        }
+        if (applicable.length === 0) {
+            throw new errors_1.UsageError("fix apply found no supported ids-family changes to apply");
+        }
+        const appliedChanges = applicable.map((change) => change.apply_kind === "git_stage_duplicate_id_rewrite"
+            ? applyGitStageDuplicateIdChange(root, change)
+            : applyDuplicateIdChange(root, change));
+        const indexReceipt = (0, index_1.rebuildDerivedIndexCaches)({ root, tolerant: true });
+        const body = {
+            action: "fix.apply",
+            ok: true,
+            schema_version: 1,
+            root,
+            family,
+            target: options.target ?? null,
+            base_ref: options.baseRef ?? null,
+            plan_id: plan.plan_id,
+            plan_hash: plan.plan_hash,
+            applied_changes: appliedChanges,
+            blocked_changes: plan.blocked_changes,
+            unsupported_changes: unsupported,
+            touched_paths: Array.from(new Set(appliedChanges.flatMap((change) => change.touched_paths))).sort(),
+            ambiguous_reference_rewrites: applicable.flatMap((change) => {
+                const after = change.after;
+                return Array.isArray(after.ambiguous_reference_rewrites) ? after.ambiguous_reference_rewrites : [];
+            }),
+            index: {
+                rebuilt: true,
+                paths: {
+                    nodes: rel(root, indexReceipt.paths.nodes),
+                    skills: rel(root, indexReceipt.paths.skills),
+                    capabilities: rel(root, indexReceipt.paths.capabilities),
+                    subgraphs: rel(root, indexReceipt.paths.subgraphs),
+                    sqlite: indexReceipt.paths.sqlite ? rel(root, indexReceipt.paths.sqlite) : null,
+                },
+            },
+            summary: {
+                applied_count: appliedChanges.length,
+                unsupported_count: unsupported.length,
+                blocked_count: plan.blocked_changes.length,
+                message: unsupported.length > 0
+                    ? "applied supported ids-family changes; unsupported findings remain review-only"
+                    : "applied supported ids-family duplicate-id repairs",
+            },
+        };
+        return {
+            ...body,
+            generated_at: new Date().toISOString(),
+            receipt_hash: sha256(body),
+        };
+    });
+}
 function runFixPlanCommand(options) {
     const payload = collectFixPlan(options);
     if (options.json) {
@@ -929,6 +1362,25 @@ function runFixPlanCommand(options) {
     console.log(`family: ${payload.family}`);
     console.log(`proposed_changes: ${payload.proposed_changes.length}`);
     console.log(`blocked_changes: ${payload.blocked_changes.length}`);
-    console.log("apply_supported: false");
-    console.log("note: fix apply is not available; rerun with --json for the machine-readable receipt");
+    console.log(`apply_supported: ${payload.summary.apply_supported}`);
+    console.log("note: use --json for the machine-readable receipt");
+}
+function runFixApplyCommand(options) {
+    const payload = collectFixApply(options);
+    if (options.json) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    console.log("fix apply");
+    console.log(`receipt_hash: ${payload.receipt_hash}`);
+    console.log(`family: ${payload.family}`);
+    console.log(`applied_changes: ${payload.applied_changes.length}`);
+    console.log(`touched_paths: ${payload.touched_paths.join(", ")}`);
+}
+function runFixIdsCommand(options) {
+    if (options.apply) {
+        runFixApplyCommand({ ...options, family: "ids" });
+        return;
+    }
+    runFixPlanCommand({ ...options, family: "ids" });
 }

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -27,14 +27,20 @@ Primary commands:
 - `mdkg task`
 - `mdkg validate`
 - `mdkg status [--json]`
-- `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]`
 
 Operator health:
 - `mdkg status [--json]` is a read-only summary for scripts and agents
 - reports mdkg version/config, git state, graph/index freshness, selected-goal state, project DB verification summary, and generated cache status
 - does not rebuild indexes, run migrations, repair files, mutate graph nodes, or change selected-goal state
-- `mdkg fix plan ...` is dry-run repair planning only; it writes nothing and `fix apply` is not exposed
-- `fix plan --json` returns a receipt-shaped plan with selected families, risk counts, paths, reason codes, and `apply_supported: false`
+- `mdkg fix plan ...` is dry-run repair planning only; it writes nothing
+- duplicate-ID graph repairs can be applied with `mdkg fix apply --family ids` or `mdkg fix ids --apply`
+- use `--base-ref main` when mainline IDs should win branch-merge repair
+- unresolved Git add/add conflict stages are split 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
+- `fix plan --json` returns a receipt-shaped plan with selected families, risk counts, paths, reason codes, and per-change `apply_supported` metadata
 
 Index backend:
 - fresh mdkg workspaces default to `index.backend: sqlite`

package/dist/init/README.md

@@ -45,8 +45,13 @@ fresh init, run `mdkg index` first so strict doctor can load generated caches.
 
 Use `mdkg fix plan --json` for dry-run repair guidance. It reports generated
 index/cache repair hints, missing graph references, and duplicate local ids as
-receipt-shaped planned changes with risk levels and `apply_supported: false`.
-`fix apply` is not exposed; repair application is intentionally deferred.
+receipt-shaped planned changes with risk levels 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.
 
 Use research spikes for investigation and planning work that should produce a
 reviewable recommendation before implementation:

package/dist/init/init-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.3.3",
+  "mdkg_version": "0.3.4",
   "files": [
     {
       "path": ".mdkg/config.json",
@@ -61,7 +61,7 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "68b5f4d2d04a4dc9a062e54a594d684b3816c0b614079eb6b08f0dca16fd0b47"
+      "sha256": "5962993e8dffd53ccbceaaedd0b8f2a868421a3a1cc16d7002b661b39b7ebf79"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
@@ -261,7 +261,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "7f27715427a6762ef987fb872c9e09976075c76fddac68c4df89387e5b8a6909"
+      "sha256": "7322e6a2c47261f87dacd15ba0d93eba0d1e32eec0900a1e9f447ad13aaae860"
     },
     {
       "path": "llms.txt",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdkg",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {
@@ -28,6 +28,7 @@
     "smoke:operator-health": "npm run build && node scripts/smoke-operator-health.js",
     "smoke:fix-plan": "npm run build && node scripts/smoke-fix-plan.js",
     "smoke:branch-conflicts": "npm run build && node scripts/smoke-branch-conflicts.js",
+    "smoke:id-repair": "npm run build && node scripts/smoke-id-repair.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",
@@ -41,7 +42,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: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",
+    "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:id-repair && 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"
   },