mdkg 0.3.2 → 0.3.4

package/dist/commands/goal.js

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

package/dist/commands/new.js

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

package/dist/graph/node.js

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

package/dist/graph/validate_graph.js

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

package/dist/init/AGENT_START.md

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

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -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`
@@ -242,14 +248,16 @@ Work semantic mirrors:
 Goal nodes:
 - `mdkg goal show <goal-id-or-qid> [--json]`
 - `mdkg goal select <goal-id-or-qid> [--json]`
+- `mdkg goal activate <goal-id-or-qid> [--json]`
 - `mdkg goal current [--json]`
 - `mdkg goal clear [--json]`
 - `mdkg goal next [goal-id-or-qid] [--json]`
 - `mdkg goal claim [goal-id-or-qid] <work-id-or-qid> [--json]`
 - `mdkg goal evaluate <goal-id-or-qid> [--json]`
-- `mdkg goal pause|resume|done <goal-id-or-qid> [--json]`
+- `mdkg goal pause|resume|done|archive <goal-id-or-qid> [--json]`
 - `mdkg goal show <goal-id-or-qid> [--ws <alias>] [--json]`
 - `mdkg goal select <goal-id-or-qid> [--ws <alias>] [--json]`
+- `mdkg goal activate <goal-id-or-qid> [--ws <alias>] [--json]`
 - `mdkg goal current [--ws <alias>] [--json]`
 - `mdkg goal next [goal-id-or-qid] [--ws <alias>] [--json]`
 - `mdkg goal claim <work-id-or-qid> [--ws <alias>] [--json]`
@@ -258,7 +266,10 @@ Goal nodes:
 - `mdkg goal pause <goal-id-or-qid> [--ws <alias>] [--json]`
 - `mdkg goal resume <goal-id-or-qid> [--ws <alias>] [--json]`
 - `mdkg goal done <goal-id-or-qid> [--ws <alias>] [--json]`
+- `mdkg goal archive <goal-id-or-qid> [--ws <alias>] [--json]`
 - goals orchestrate recursive progress through explicit `scope_refs`; tasks, bugs, tests, spikes, and features remain concrete executable units
+- `goal activate` makes one local root goal active, pauses competing local active goals in the same workspace, and writes selected-goal state
+- `goal archive` marks a superseded historical goal archived so it remains readable but not actionable
 - `goal next` is read-only; use `goal claim` to set `active_node`
 - `mdkg goal evaluate` is report-only and never runs commands from `required_checks`
 - skill improvements discovered during normal goal execution should be recorded as candidates or proposals unless the active node is skill-maintenance

package/dist/init/README.md

@@ -35,7 +35,7 @@ mdkg fix plan --json
 mdkg validate
 ```
 
-This repo is already initialized. Use `mdkg upgrade` to preview safe scaffold updates, `mdkg index` to create or refresh generated graph/skill/capability/subgraph and SQLite caches after init, `mdkg new` to create work, `mdkg new goal "..."` plus `mdkg goal select/current/next/claim/evaluate` for recursive long-running objectives, `mdkg search`/`mdkg show` to inspect graph state, `mdkg capability ...` to inspect cached skill/spec/work/core/design capabilities, `mdkg spec ...` for focused optional SPEC records, `mdkg capability resolve ...` to rank local and subgraph capabilities, `mdkg archive ...` to register source/artifact sidecars, `mdkg work ...` to create work contract/order/receipt semantic mirrors and deterministic trigger/verification records, `mdkg bundle ...` to create full graph snapshot bundles, `mdkg subgraph ...` to register read-only child graph planning views, `mdkg pack <id>` to build deterministic context, and `mdkg validate` before closeout.
+This repo is already initialized. Use `mdkg upgrade` to preview safe scaffold updates, `mdkg index` to create or refresh generated graph/skill/capability/subgraph and SQLite caches after init, `mdkg new` to create work, `mdkg new goal "..."` plus `mdkg goal activate/current/next/claim/evaluate` for recursive long-running objectives, `mdkg search`/`mdkg show` to inspect graph state, `mdkg capability ...` to inspect cached skill/spec/work/core/design capabilities, `mdkg spec ...` for focused optional SPEC records, `mdkg capability resolve ...` to rank local and subgraph capabilities, `mdkg archive ...` to register source/artifact sidecars, `mdkg work ...` to create work contract/order/receipt semantic mirrors and deterministic trigger/verification records, `mdkg bundle ...` to create full graph snapshot bundles, `mdkg subgraph ...` to register read-only child graph planning views, `mdkg pack <id>` to build deterministic context, and `mdkg validate` before closeout.
 
 Use `mdkg status --json` for a read-only operator summary of Git, graph,
 selected-goal, project DB, and generated-cache health before mutating work. Use
@@ -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.2",
+  "mdkg_version": "0.3.4",
   "files": [
     {
       "path": ".mdkg/config.json",
@@ -61,7 +61,7 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "c08de01602698af7eb46b70e9459df9c2fa6e6c32c06b2daab3f697baa450e0d"
+      "sha256": "5962993e8dffd53ccbceaaedd0b8f2a868421a3a1cc16d7002b661b39b7ebf79"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
@@ -71,7 +71,7 @@
     {
       "path": ".mdkg/skills/pursue-mdkg-goal/SKILL.md",
       "category": "default_skill",
-      "sha256": "fd64f666fb1329c392ff0979ed9999b71ad948cbca6a191502eb2cdfd76ec825"
+      "sha256": "2bc888092d95b362e402494af4dbe6909204bd5578613d6159753a84efaae16d"
     },
     {
       "path": ".mdkg/skills/select-work-and-ground-context/SKILL.md",
@@ -246,7 +246,7 @@
     {
       "path": "AGENT_START.md",
       "category": "startup_doc",
-      "sha256": "cf58e37c72be2593f1d920520dbdc6e316182bfda5c49837443a8b18024504c7"
+      "sha256": "46e734b6eae92eb957c3e29fb4d206e4be3fd6d32dd00e888e01a0dc75979428"
     },
     {
       "path": "AGENTS.md",
@@ -261,7 +261,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "888c5ce1372c0a7ba2c24bfe0aea97e221804cab1fa8940e06dc050330830a76"
+      "sha256": "7322e6a2c47261f87dacd15ba0d93eba0d1e32eec0900a1e9f447ad13aaae860"
     },
     {
       "path": "llms.txt",

package/dist/init/skills/default/pursue-mdkg-goal/SKILL.md

@@ -27,7 +27,8 @@ Move one durable mdkg goal forward without losing scope, evidence, or user inten
 ## Steps
 
 1. Resolve the goal:
-   - If a goal id is provided, run `mdkg goal select <goal-id>`.
+   - If a goal id is provided and you are beginning durable work on it, run `mdkg goal activate <goal-id>`.
+   - Use `mdkg goal select <goal-id>` only when you need a local pointer without changing lifecycle state.
    - Otherwise run `mdkg goal current`.
    - If the result is missing or ambiguous, ask the user to select a goal.
 2. Inspect the goal with `mdkg goal show <goal-id>` and build context with `mdkg pack <goal-id>`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdkg",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {
@@ -28,8 +28,10 @@
     "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",
     "smoke:bundle": "npm run build && node scripts/smoke-bundle.js",
     "smoke:bundle-import": "npm run smoke:subgraph",
     "smoke:visibility": "npm run build && node scripts/smoke-visibility.js",
@@ -40,7 +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: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"
   },