mdkg 0.3.3 → 0.3.5

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -22,19 +22,27 @@ Primary commands:
 - `mdkg spec`
 - `mdkg archive`
 - `mdkg bundle`
+- `mdkg graph`
+- `mdkg subgraph`
 - `mdkg work`
 - `mdkg goal`
 - `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`
@@ -198,6 +206,21 @@ Graph snapshot bundles:
 - public bundles include only public workspace content and public archive sidecars
 - public bundle creation fails when public records reference private graph, archive, or subgraph records
 
+Graph clone, fork, and template import:
+- `mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]`
+- `mdkg graph fork <source-bundle-or-mdkg-dir> --target <path> [--start-goal <goal-id>] [--json]`
+- `mdkg graph import-template <source-bundle-or-mdkg-dir> [--start-goal <goal-id>] [--select-goal] [--id-prefix <prefix>] [--dry-run] [--apply] [--json]`
+- `graph clone` and `graph fork` preserve IDs because the target is a separate graph namespace
+- clone/fork targets must be empty or absent and stay under the current mdkg root
+- live directory sources are never mutated; clone/fork refuses targets nested inside a live source directory
+- `graph fork --start-goal <goal-id>` writes selected-goal state in the target graph after validation
+- `graph import-template` imports authored `.mdkg/work/*.md` template nodes into the current repo and skips config, generated indexes, archive payloads, bundles, and materialized subgraph views
+- `graph import-template` defaults to dry-run unless `--apply` is supplied
+- same-repo template import rewrites canonical numeric IDs to the next unused ID by type prefix and rewrites structured refs plus safe body-local id/qid mentions
+- colliding semantic template IDs require `--id-prefix`
+- `--select-goal` requires `--start-goal` and writes selected-goal state only after apply validation
+- subgraphs remain read-only bundle projections for orchestration context; use `graph clone|fork|import-template` when authored graph state should be created
+
 Subgraph orchestration:
 - `mdkg subgraph add <alias> <bundle-path> [--visibility private|internal|public] [--profile private|public] [--source-path <path>] [--json]`
 - `mdkg subgraph list [--json]`

package/dist/init/README.md

@@ -29,13 +29,14 @@ mdkg capability search "..."
 mdkg spec list --json
 mdkg archive list
 mdkg bundle create --profile private
+mdkg graph clone .mdkg/bundles/private/all.mdkg.zip --target demos/demo-1 --json
 mdkg subgraph list --json
 mdkg status --json
 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 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.
+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 graph ...` to clone/fork/import authored graph templates, `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 +46,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:
@@ -153,6 +159,22 @@ mdkg bundle verify .mdkg/bundles/private/all.mdkg.zip
 
 Use this as a pre-commit recommendation only when the repo tracks archive caches or `.mdkg/bundles/`. Private bundles are local graph transport artifacts and may be tracked in private repos when configured. Public bundles require selected workspaces with `visibility: public` and fail closed when public records reference private graph, archive, or subgraph records.
 
+Clone or fork an authored graph into a separate repo/workspace while preserving IDs:
+
+```bash
+mdkg graph clone .mdkg/bundles/private/all.mdkg.zip --target demos/demo-1 --json
+mdkg graph fork templates/website-template-mdkg --target demos/live-build --start-goal goal-1 --json
+```
+
+Import a template graph into the current repo with deterministic ID and link rewrites:
+
+```bash
+mdkg graph import-template templates/website-template-mdkg --start-goal goal-1 --select-goal --dry-run --json
+mdkg graph import-template templates/website-template-mdkg --start-goal goal-1 --select-goal --apply --json
+```
+
+`graph clone` and `graph fork` preserve IDs because the target is a separate graph namespace. `graph import-template` rewrites canonical numeric IDs for same-repo imports and requires `--id-prefix` for colliding semantic IDs. Subgraphs remain read-only planning views; use `mdkg graph ...` when authored graph state should be created.
+
 Register child bundle snapshots as read-only subgraphs with:
 
 ```bash

package/dist/init/init-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.3.3",
+  "mdkg_version": "0.3.5",
   "files": [
     {
       "path": ".mdkg/config.json",
@@ -61,7 +61,7 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "68b5f4d2d04a4dc9a062e54a594d684b3816c0b614079eb6b08f0dca16fd0b47"
+      "sha256": "a3b059cb0ea5625f9888fbcee52ddf13491e033046d8c3f3846574d8667ad234"
     },
     {
       "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": "220b461553310a8248d53f01fae132d4ca433659da679e401e3ce6abe2592cb7"
     },
     {
       "path": "llms.txt",

package/dist/util/argparse.js

@@ -95,6 +95,8 @@ const VALUE_FLAGS = new Set([
     "--target",
     "--snapshot",
     "--family",
+    "--start-goal",
+    "--id-prefix",
 ]);
 const BOOLEAN_FLAGS = new Set([
     "--tolerant",
@@ -132,6 +134,7 @@ const BOOLEAN_FLAGS = new Set([
     "--allow-dirty",
     "--clean",
     "--gitignore",
+    "--select-goal",
 ]);
 const FLAG_ALIASES = {
     "--o": "--out",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdkg",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {
@@ -28,10 +28,12 @@
     "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:graph-clone": "npm run build && node scripts/smoke-graph-clone.js",
     "smoke:bundle-import": "npm run smoke:subgraph",
     "smoke:visibility": "npm run build && node scripts/smoke-visibility.js",
     "smoke:sqlite": "npm run build && node scripts/smoke-sqlite.js",
@@ -41,7 +43,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:graph-clone && 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"
   },