mdkg 0.3.8 → 0.4.0

package/dist/core/config.js

@@ -3,6 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SKILL_MIRROR_TARGETS = void 0;
+exports.defaultCustomizationConfig = defaultCustomizationConfig;
 exports.validateConfigSchema = validateConfigSchema;
 exports.loadConfig = loadConfig;
 const fs_1 = __importDefault(require("fs"));
@@ -30,6 +32,7 @@ const DEFAULT_ARCHIVE_LARGE_CACHE_WARNING_BYTES = 26214400;
 const DEFAULT_SQLITE_COMMIT_WARNING_BYTES = 52428800;
 const DEFAULT_LOCK_TIMEOUT_MS = 10000;
 const DEFAULT_SUBGRAPH_MAX_STALE_SECONDS = 3600;
+exports.DEFAULT_SKILL_MIRROR_TARGETS = [".agents/skills", ".claude/skills"];
 const DEFAULT_PROJECT_DB_CONFIG = {
     enabled: false,
     schema_version: project_db_1.PROJECT_DB_CONFIG_SCHEMA_VERSION,
@@ -41,6 +44,20 @@ const DEFAULT_PROJECT_DB_CONFIG = {
     receipts_path: project_db_1.PROJECT_DB_RECEIPTS_DIR,
     migration_table: project_db_1.PROJECT_DB_MIGRATION_TABLE,
 };
+function defaultCustomizationConfig() {
+    return {
+        standards: {
+            profile: "default",
+            refs: [],
+        },
+        core_docs: {
+            custom_paths: [],
+        },
+        skill_mirrors: {
+            targets: [...exports.DEFAULT_SKILL_MIRROR_TARGETS],
+        },
+    };
+}
 function isObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -171,6 +188,35 @@ function requireKnownLowercaseUniqueStringArray(value, path, allowed, errors, al
     }
     return items;
 }
+function requireUniqueStringArray(value, path, errors, allowEmpty = false) {
+    const items = requireStringArray(value, path, errors);
+    if (items === undefined) {
+        return undefined;
+    }
+    if (items.length === 0) {
+        if (!allowEmpty) {
+            errors.push(`${path} must not be empty`);
+        }
+        return items;
+    }
+    const seen = new Set();
+    for (let i = 0; i < items.length; i += 1) {
+        const item = items[i];
+        if (item.trim().length === 0) {
+            errors.push(`${path}[${i}] must not be empty`);
+            continue;
+        }
+        if (item !== item.trim()) {
+            errors.push(`${path}[${i}] must not include surrounding whitespace`);
+        }
+        if (seen.has(item)) {
+            errors.push(`${path} must not contain duplicate value "${item}"`);
+            continue;
+        }
+        seen.add(item);
+    }
+    return items;
+}
 function requireObject(value, path, errors) {
     if (!isObject(value)) {
         errors.push(`${path} must be an object`);
@@ -213,6 +259,33 @@ function requireContainedPath(value, path, errors) {
         return undefined;
     }
 }
+function requireContainedPathArray(value, path, errors, allowEmpty = true) {
+    if (!Array.isArray(value)) {
+        errors.push(`${path} must be an array of relative paths`);
+        return undefined;
+    }
+    if (value.length === 0) {
+        if (!allowEmpty) {
+            errors.push(`${path} must not be empty`);
+        }
+        return [];
+    }
+    const items = [];
+    const seen = new Set();
+    for (let i = 0; i < value.length; i += 1) {
+        const normalized = requireContainedPath(value[i], `${path}[${i}]`, errors);
+        if (!normalized) {
+            continue;
+        }
+        if (seen.has(normalized)) {
+            errors.push(`${path} must not contain duplicate path "${normalized}"`);
+            continue;
+        }
+        seen.add(normalized);
+        items.push(normalized);
+    }
+    return items;
+}
 function requireSqlIdentifier(value, path, errors) {
     const raw = requireString(value, path, errors);
     if (raw === undefined) {
@@ -266,6 +339,10 @@ function validateConfigSchema(raw) {
         ? { output_dir: ".mdkg/bundles", default_profile: "private" }
         : requireObject(raw.bundles, "bundles", errors);
     const dbRaw = raw.db === undefined ? DEFAULT_PROJECT_DB_CONFIG : requireObject(raw.db, "db", errors);
+    const customizationDefaults = defaultCustomizationConfig();
+    const customizationRaw = raw.customization === undefined
+        ? customizationDefaults
+        : requireObject(raw.customization, "customization", errors);
     if (raw.bundle_imports !== undefined && raw.subgraphs !== undefined) {
         errors.push("config must not define both subgraphs and legacy bundle_imports");
     }
@@ -370,6 +447,60 @@ function validateConfigSchema(raw) {
             };
         }
     }
+    let customization;
+    if (customizationRaw) {
+        const standardsRaw = customizationRaw.standards === undefined
+            ? customizationDefaults.standards
+            : requireObject(customizationRaw.standards, "customization.standards", errors);
+        const coreDocsRaw = customizationRaw.core_docs === undefined
+            ? customizationDefaults.core_docs
+            : requireObject(customizationRaw.core_docs, "customization.core_docs", errors);
+        const skillMirrorsRaw = customizationRaw.skill_mirrors === undefined
+            ? customizationDefaults.skill_mirrors
+            : requireObject(customizationRaw.skill_mirrors, "customization.skill_mirrors", errors);
+        const standardsProfile = standardsRaw
+            ? standardsRaw.profile === undefined
+                ? customizationDefaults.standards.profile
+                : requireString(standardsRaw.profile, "customization.standards.profile", errors)
+            : undefined;
+        const standardsRefs = standardsRaw
+            ? standardsRaw.refs === undefined
+                ? customizationDefaults.standards.refs
+                : requireUniqueStringArray(standardsRaw.refs, "customization.standards.refs", errors, true)
+            : undefined;
+        const coreDocPaths = coreDocsRaw
+            ? coreDocsRaw.custom_paths === undefined
+                ? customizationDefaults.core_docs.custom_paths
+                : requireContainedPathArray(coreDocsRaw.custom_paths, "customization.core_docs.custom_paths", errors, true)
+            : undefined;
+        const mirrorTargets = skillMirrorsRaw
+            ? skillMirrorsRaw.targets === undefined
+                ? customizationDefaults.skill_mirrors.targets
+                : requireContainedPathArray(skillMirrorsRaw.targets, "customization.skill_mirrors.targets", errors, true)
+            : undefined;
+        if (standardsProfile !== undefined) {
+            if (standardsProfile.trim().length === 0) {
+                errors.push("customization.standards.profile must not be empty");
+            }
+            if (standardsProfile !== standardsProfile.trim()) {
+                errors.push("customization.standards.profile must not include surrounding whitespace");
+            }
+        }
+        if (standardsProfile && standardsRefs && coreDocPaths && mirrorTargets) {
+            customization = {
+                standards: {
+                    profile: standardsProfile,
+                    refs: standardsRefs,
+                },
+                core_docs: {
+                    custom_paths: coreDocPaths,
+                },
+                skill_mirrors: {
+                    targets: mirrorTargets,
+                },
+            };
+        }
+    }
     const packLimitsRaw = packRaw ? requireObject(packRaw.limits, "pack.limits", errors) : undefined;
     const pack = packRaw
         ? {
@@ -605,6 +736,7 @@ function validateConfigSchema(raw) {
         capabilities: capabilities,
         bundles: bundles,
         db: db,
+        customization: customization,
         subgraphs,
         pack: pack,
         templates: templates,

package/dist/init/AGENT_START.md

@@ -6,14 +6,15 @@ mdkg is pre-v1 public alpha software. Treat generated graph, cache, bundle, and
 
 Read these files in order:
 1. `.mdkg/core/SOUL.md` if it exists
-2. `.mdkg/core/HUMAN.md` if it exists
-3. `.mdkg/README.md`
-4. `CLI_COMMAND_MATRIX.md`
+2. `.mdkg/core/COLLABORATION.md` if it exists
+3. `.mdkg/core/HUMAN.md` if it exists as a legacy alias
+4. `.mdkg/README.md`
+5. `CLI_COMMAND_MATRIX.md`
 
 Trust order:
 - source code
 - mdkg rules, design docs, decisions, and work nodes
-- SOUL/HUMAN collaboration anchors
+- SOUL/COLLABORATION anchors and legacy HUMAN notes
 - relevant skills
 - chat history
 

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -177,7 +177,7 @@ Checkpoint commands:
 Agent bootstrap:
 - `mdkg init --agent`
 - published bootstrap config is root-only by default
-- `mdkg init --agent` creates the complete startup docs, wrapper docs, default mdkg skills, event log, registry, and skill mirrors
+- `mdkg init --agent` creates the complete startup docs, wrapper docs, `SOUL.md` / `COLLABORATION.md` core docs, legacy `HUMAN.md`, default mdkg skills, event log, registry, and configured skill mirrors
 - removed flags `--llm`, `--agents`, `--claude`, and `--omni` fail before mutation with guidance to use `mdkg init --agent`
 
 Upgrade:

package/dist/init/README.md

@@ -96,9 +96,9 @@ Read `AGENT_START.md` first when this repo includes it.
 
 ## Pack Profiles
 
-- `--pack-profile standard`: full body (current default behavior)
-- `--pack-profile concise`: summary body with code stripped by default
-- `--pack-profile headers`: metadata-only body (`none`)
+- `--profile standard`: full body (current default behavior)
+- `--profile concise`: summary body with code stripped by default
+- `--profile headers`: metadata-only body (`none`)
 
 `--max-tokens` is a heuristic limit based on `chars / 4`.
 

package/dist/init/config.json

@@ -32,6 +32,21 @@
     "receipts_path": ".mdkg/db/receipts",
     "migration_table": "mdkg_schema_migration"
   },
+  "customization": {
+    "standards": {
+      "profile": "default",
+      "refs": []
+    },
+    "core_docs": {
+      "custom_paths": []
+    },
+    "skill_mirrors": {
+      "targets": [
+        ".agents/skills",
+        ".claude/skills"
+      ]
+    }
+  },
   "subgraphs": {},
   "pack": {
     "default_depth": 2,

package/dist/init/core/COLLABORATION.md

@@ -0,0 +1,45 @@
+---
+id: rule-7
+type: rule
+title: collaboration profile and operator preferences
+tags: [collaboration, preferences, operator]
+owners: []
+links: []
+artifacts: []
+relates: [rule-human]
+refs: [dec-53]
+aliases: [collaboration, operator-profile]
+created: 2026-06-27
+updated: 2026-06-27
+---
+
+# Purpose
+
+Capture stable collaboration preferences, operating boundaries, and repo-specific
+human expectations so agents can work with less ambiguity.
+
+# Scope
+
+Applies to planning, implementation, review, release, and handoff interactions in
+this repository.
+
+# Compatibility
+
+`COLLABORATION.md` is canonical. `HUMAN.md` remains a one-release legacy alias for
+repos and agent prompts that still reference it; read `COLLABORATION.md` first and
+then use `HUMAN.md` only for compatibility notes not yet migrated.
+
+# Requirements
+
+- Keep top goals, boundaries, and style preferences current.
+- Include ask-before-doing constraints for risky or high-impact actions.
+- Record preferred environment assumptions and validation commands.
+- Preserve local operator customizations during `mdkg upgrade --apply`.
+
+# Notes
+
+Suggested prompts:
+- What are your top 3 goals in this repo right now?
+- What should never happen without confirmation?
+- What coding/review style should the agent prefer?
+- What OS/runtime/test commands should be assumed?

package/dist/init/core/HUMAN.md

@@ -10,9 +10,15 @@ relates: []
 refs: []
 aliases: [human]
 created: 2026-03-10
-updated: 2026-03-10
+updated: 2026-06-27
 ---
 
+# Compatibility
+
+`HUMAN.md` is a one-release legacy alias. Read
+`.mdkg/core/COLLABORATION.md` first when it exists, then use this file only for
+older local notes that have not yet moved to the canonical collaboration profile.
+
 # Purpose
 
 Capture stable collaboration preferences and boundaries so agents can work with less ambiguity.

package/dist/init/core/core.md

@@ -4,6 +4,7 @@
 # This list is included by `mdkg pack --verbose`.
 
 rule-soul
+rule-7
 rule-human
 rule-1
 rule-2

package/dist/init/core/rule-1-mdkg-conventions.md

@@ -92,6 +92,9 @@ Reserved rule IDs allowed by contract:
 - `rule-soul`
 - `rule-human`
 
+`rule-7` is the current canonical collaboration profile. `rule-human` remains a
+one-release legacy alias through `HUMAN.md`.
+
 Examples:
 - `task-183`
 - `edd-14`

package/dist/init/core/rule-3-cli-contract.md

@@ -114,20 +114,20 @@ If a user provides an unqualified ID and it is ambiguous globally:
     - `llms.txt`
     - `CLI_COMMAND_MATRIX.md`
     - `.mdkg/core/SOUL.md` (`id: rule-soul`)
-    - `.mdkg/core/HUMAN.md` (`id: rule-human`)
+    - `.mdkg/core/COLLABORATION.md` (`id: rule-7`)
+    - `.mdkg/core/HUMAN.md` (`id: rule-human`, one-release legacy alias)
     - seeded canonical skills:
       - `.mdkg/skills/select-work-and-ground-context/SKILL.md`
       - `.mdkg/skills/build-pack-and-execute-task/SKILL.md`
       - `.mdkg/skills/verify-close-and-checkpoint/SKILL.md`
     - `.mdkg/skills/registry.md`
     - `.mdkg/work/events/events.jsonl`
-    - `.agents/skills/`
-    - `.claude/skills/`
-    - deterministic `core.md` pin insertion (`rule-soul`, then `rule-human`)
+    - configured skill mirror targets, defaulting to `.agents/skills/` and `.claude/skills/`
+    - deterministic `core.md` pin insertion (`rule-soul`, then `rule-7`, then `rule-human`)
     - ignore policy for generated JSON index/temp/lock files, `.mdkg/pack/`, and raw archive source copies under `.mdkg/archive/**/source/`
   - mirrored skills are append-focused outputs:
     - `.mdkg/skills/` remains canonical
-    - unrelated existing folders under `.agents/skills/` and `.claude/skills/` are preserved
+    - unrelated existing folders under configured mirror targets are preserved
     - same-slug collisions fail by default unless explicitly forced through `mdkg skill sync --force`
 
 ### Guide

package/dist/init/init-manifest.json

@@ -1,17 +1,22 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.3.8",
+  "mdkg_version": "0.4.0",
   "files": [
     {
       "path": ".mdkg/config.json",
       "category": "config",
-      "sha256": "8055c72aa3c55f8a49d532a735bc29e3baa2e2bf478e9d092b83bec9e46fa78c"
+      "sha256": "715e2f55843dc31f66d4b7d333b5f89ea2aeeacc30f5dfaf7d3fd9f2c41e5fb0"
+    },
+    {
+      "path": ".mdkg/core/COLLABORATION.md",
+      "category": "core",
+      "sha256": "ef60b65b54a57ed54984a49f5ed14453cb4e47170a5660be94eceec26b92b01f"
     },
     {
       "path": ".mdkg/core/core.md",
       "category": "core",
-      "sha256": "d87beecf4229535c0d0feea7deae28b97d0681105a1c282d9961e97918f0bbe8"
+      "sha256": "7d8a5ee16433ac8057234c84c2603a9d568d538f17f0488572da15f59603ca0f"
     },
     {
       "path": ".mdkg/core/guide.md",
@@ -21,12 +26,12 @@
     {
       "path": ".mdkg/core/HUMAN.md",
       "category": "core",
-      "sha256": "75d2e015cd5ba61062cb84246017ee4f4221610d4a56e4a0b332271b90694965"
+      "sha256": "945fb5cb47945735b9529f2b0a322630b3e8aef1c3e69c4ce85dd2db3e905cca"
     },
     {
       "path": ".mdkg/core/rule-1-mdkg-conventions.md",
       "category": "core",
-      "sha256": "15f886e6661046de45ad798c292d74cc1ff3cc14c8cfcc82ed0b8c35635d0477"
+      "sha256": "03db1635d170331517efb0ac24351b477a8020a96e51edf5bd67910a49bb5db7"
     },
     {
       "path": ".mdkg/core/rule-2-context-pack-rules.md",
@@ -36,7 +41,7 @@
     {
       "path": ".mdkg/core/rule-3-cli-contract.md",
       "category": "core",
-      "sha256": "f61b84ff6e5abae91365c4f623ccbd78f25dfcfef09822fefb3abf0119d65739"
+      "sha256": "362fb8f22525f51c15ef54d81f63ebef4ab4b1dbaf37bd1415462a204ab78e45"
     },
     {
       "path": ".mdkg/core/rule-4-repo-safety-and-ignores.md",
@@ -61,7 +66,12 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "e876acfbf3e9de411cd45eb86e7e9bff821f8a5dd6dc933bd6da4ac88a9686e6"
+      "sha256": "faaf4bb697eded7c6baf6cb44a2a6c04feabfc250cac3bcb4be6b95e7a3bb02a"
+    },
+    {
+      "path": ".mdkg/skills/author-mdkg-skill/SKILL.md",
+      "category": "default_skill",
+      "sha256": "9ea196cb778e6a777c945b3bba9d51c7574602f413e9a1d5e01e2b95918c0873"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
@@ -71,17 +81,17 @@
     {
       "path": ".mdkg/skills/pursue-mdkg-goal/SKILL.md",
       "category": "default_skill",
-      "sha256": "2bc888092d95b362e402494af4dbe6909204bd5578613d6159753a84efaae16d"
+      "sha256": "0545b011232d6924d84d80ad4b33153e591249d440c55481f125b37923c298d5"
     },
     {
       "path": ".mdkg/skills/select-work-and-ground-context/SKILL.md",
       "category": "default_skill",
-      "sha256": "e50fc3b1a2c79a9a3544ca9df1bf4ca9c312e7c3a51d5e4c6f3314341eca268b"
+      "sha256": "95faee88875233dd2ed2039e941fbe879e3ccf619e1f9f18e3f2313ac5033409"
     },
     {
       "path": ".mdkg/skills/verify-close-and-checkpoint/SKILL.md",
       "category": "default_skill",
-      "sha256": "3e4137b7b6a71f088dee79b5ee2f4743aefa3b43adae07337307db89a24416b6"
+      "sha256": "1e3982ad80a0a8b94d43a80e2b7143a938f6e01aa898b86d0410911f61361107"
     },
     {
       "path": ".mdkg/templates/default/archive.md",
@@ -301,7 +311,7 @@
     {
       "path": "AGENT_START.md",
       "category": "startup_doc",
-      "sha256": "0d3bb2f9ea156f53c1bf68595e591578caadc18d296fa919e71ea1a3d9a968e8"
+      "sha256": "91e31ae818b29f62ebe77ac24f7e1a2bd10a4fedfc1684da935f0849aaf6d200"
     },
     {
       "path": "AGENTS.md",
@@ -316,12 +326,12 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "8f426fd8da402b4b550b71e7ec3882c614ceb2d79d23c47b9c27bca7e39fadb2"
+      "sha256": "82c509b91498131304ff2bc94bb7eb2f29c3c207a00bc8bcaf8a6ab52ff9e689"
     },
     {
       "path": "llms.txt",
       "category": "startup_doc",
-      "sha256": "8316bb8f634c6fb290ef1591e9c5b9786a2ddc06d25ab7d448fce8f4aebf65b8"
+      "sha256": "108ac1feb3e11824c9cfc5116aaa83355cb461ad9b0ec5c4bb244f6a70276f31"
     }
   ]
 }

package/dist/init/llms.txt

@@ -4,7 +4,8 @@ Read `AGENT_START.md` first.
 
 Key files:
 - `.mdkg/core/SOUL.md`
-- `.mdkg/core/HUMAN.md`
+- `.mdkg/core/COLLABORATION.md`
+- `.mdkg/core/HUMAN.md` (legacy alias for one release)
 - `.mdkg/README.md`
 - `CLI_COMMAND_MATRIX.md`