mdkg 0.3.8 → 0.3.9

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/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.3.9",
   "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",
@@ -63,6 +68,11 @@
       "category": "mdkg_doc",
       "sha256": "e876acfbf3e9de411cd45eb86e7e9bff821f8a5dd6dc933bd6da4ac88a9686e6"
     },
+    {
+      "path": ".mdkg/skills/author-mdkg-skill/SKILL.md",
+      "category": "default_skill",
+      "sha256": "9ea196cb778e6a777c945b3bba9d51c7574602f413e9a1d5e01e2b95918c0873"
+    },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
       "category": "default_skill",
@@ -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`
 

package/dist/init/skills/default/author-mdkg-skill/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: author-mdkg-skill
+description: Create or update an mdkg SKILL.md or MANIFEST.md when a repeatable workflow, capability, agent, tool, runtime, API, or projection contract should become durable mdkg-authored knowledge.
+tags: [stage:plan, writer:orchestrator, mdkg, skills, authoring]
+version: 0.2.0
+authors: [mdkg]
+links: [AGENT_START.md, CLI_COMMAND_MATRIX.md, .mdkg/design/edd-5-mdkg-skills-integration-guide-v0-4-agent-skills-standard-and-packs.md]
+---
+
+# Goal
+
+Create or update focused mdkg-authored SKILL.md and MANIFEST.md assets that make
+repeatable workflows and durable capabilities explicit without creating
+duplicated procedures or projection-only behavior.
+
+## When To Use
+
+- When a repo workflow is repeated often enough to deserve a reusable skill
+- When an existing skill no longer matches the current command surface or docs
+- When a builder asks to codify a procedure for future humans or agents
+- When a capability, agent, tool, runtime image, API, model, or integration
+  needs a durable MANIFEST before it is projected into a runtime-specific config
+- When `.codex/agents` or another projection surface contains behavior that
+  should be mirrored into durable mdkg/MANIFEST/SKILL state
+
+## Inputs
+
+- Repo root
+- Workflow trigger and desired outcome
+- Any existing related skills, docs, or command references
+- Candidate capability, resource, agent, tool, runtime, API, model, or
+  integration boundary
+- Source mdkg nodes and intended projection targets, if any
+
+## Required Output Sections
+
+For SKILL.md output, include:
+
+- Purpose
+- When to use
+- Inputs
+- Outputs
+- Required capabilities
+- Resources touched
+- Steps
+- Validation checks
+- Closeout evidence
+- Failure modes
+- Safety rules
+- Related manifests
+- Projection targets
+- Open questions
+
+For MANIFEST.md output, include:
+
+- Identity
+- Purpose
+- Scope
+- Non-goals
+- Status
+- Owners
+- Source mdkg nodes
+- Resource URIs
+- Capabilities
+- Inputs
+- Outputs
+- Dependencies
+- Security boundaries
+- Validation checks
+- Closeout evidence
+- Projection targets
+- Versioning
+- Change policy
+- Open questions
+
+## Steps
+
+1. Check for an existing fit first with `mdkg skill list`, `mdkg skill search`, and `mdkg skill show <slug>`.
+2. If an existing skill already covers the workflow, update it instead of creating a near-duplicate.
+3. If a manifest already covers the capability, update that MANIFEST or create a
+   repair task instead of adding behavior only to a projection file.
+4. Use existing templates from `.mdkg/templates/skills/` and
+   `.mdkg/templates/specs/` before proposing a new template family.
+5. If the workflow is really task mutation or event provenance, prefer teaching
+   `mdkg task ...` and `mdkg event ...` for structured fields while still
+   allowing markdown narrative edits where they fit better.
+6. If a new skill is justified, scaffold it with
+   `mdkg skill new <slug> "<name>" --description "..."`.
+7. Write the description so it says both what the skill does and when to use it.
+8. Add only the minimum tags needed for discovery, including the correct
+   `stage:*` tag and a single `writer:*` tag.
+9. Keep the body concise and procedural; move detailed reference material into
+   `references/` only when needed.
+10. Distinguish durable source from projection:
+    mdkg/MANIFEST/SKILL is source; `.codex/agents`, future runtime manifests, and
+    protocol resources are projections.
+11. Add validation checks and closeout evidence to every authored or revised
+    SKILL/MANIFEST.
+12. If input is incomplete, create repair tasks instead of guessing.
+13. Validate the new or updated skill with `mdkg skill validate <slug>`.
+14. If the skill changes the public workflow, update `AGENT_START.md`,
+    `CLI_COMMAND_MATRIX.md`, root onboarding docs, and the skill registry in the
+    same pass.
+15. When mirrored skill folders are enabled, run `mdkg skill sync` after broad
+    manual changes so every configured `.mdkg/config.json`
+    `customization.skill_mirrors.targets` path stays current. The default
+    targets are `.agents/skills/` and `.claude/skills/`; other agent-local
+    skill roots may be configured by the repo.
+
+## Outputs
+
+- One valid `SKILL.md` using the mdkg canonical section shape
+- One valid `MANIFEST.md` when the work is a durable capability, agent, project,
+  tool, runtime, API, model, or integration contract
+- Any needed `references/`, `assets/`, or opt-in `scripts/` scaffolding
+- Updated docs and registry entries when the workflow surface changed
+- Repair tasks for weak, missing, ambiguous, projection-only, or unsafe input
+- Validation and closeout evidence sufficient for a future agent to trust the
+  asset
+
+## Required Capabilities
+
+- mdkg skill discovery
+- mdkg capability discovery
+- Markdown frontmatter and body authoring
+- source/projection boundary review
+- validation and closeout evidence review
+
+## Resources Touched
+
+- `.mdkg/skills/<slug>/SKILL.md`
+- `.mdkg/templates/skills/`
+- `.mdkg/templates/specs/`
+- relevant `MANIFEST.md` nodes or template files, with legacy `SPEC.md`
+  references retained only for compatibility
+- configured mirrored skill roots only through `mdkg skill sync`
+
+## Validation Checks
+
+- `mdkg skill validate <slug>`
+- `mdkg skill sync --json` when mirror targets are present
+- `mdkg capability search "<skill or manifest concept>" --json`
+- `mdkg validate --changed-only --json`
+- `mdkg validate`
+- Template coverage check when template files are changed
+- Projection validation report when `.codex/agents` or another projection
+  target is involved
+
+## Closeout Evidence
+
+- Changed skill or MANIFEST paths
+- Checks run and results
+- Related mdkg nodes
+- Projection targets reviewed
+- Repair tasks created for incomplete inputs
+- Explicit note that no generator/exporter was implemented unless selected work
+  asked for it
+
+## Safety Rules
+
+- Do not create skills for one-off tasks or vague advice.
+- Prefer repo truth over chat memory when deciding the skill body and examples.
+- Do not add `scripts/` unless instructions are insufficient and deterministic execution really needs them.
+- Only the durable writer stage should commit the new or updated skill.
+- mdkg indexes and discovers skills, but does not execute skill scripts.
+- Do not treat `.codex/agents`, future runtime manifests, or package exports as
+  durable source of truth.
+- Do not create new `SPEC.md` capability docs; use `MANIFEST.md`. Keep legacy
+  `SPEC.md` references only when documenting compatibility or migration repair.
+- Do not export secrets, provider credentials, raw auth state, production
+  controls, wallet/ledger state, or local-only user paths into templates or
+  projections.
+- Do not create a skill-factory-agent until SKILL/MANIFEST templates and projection
+  doctrine are stable.
+- Optional `draft_uri` fields are future-facing hints, not finalized protocol
+  semantics. Use generic examples such as `capability://repo.inspect` or
+  `mdkg://capability/repo.inspect` in canonical mdkg templates.
+- Do not use downstream product names or product-specific URI schemes as public
+  mdkg template examples.
+
+## Failure Handling
+
+- If the trigger or writer role is unclear, stop and resolve that before authoring the skill.
+- If multiple skills overlap, merge or narrow them instead of creating redundant procedures.
+- If the workflow still feels too broad, split it into smaller skills before finalizing.
+- If durable behavior exists only in a projection file, create or update a MANIFEST
+  and record projection repair work.
+- If a requested template family is missing, propose a template backlog task
+  before inventing a one-off shape.
+- If validation cannot run, record the exact blocker and keep the work open.
+
+## Related Manifests
+
+- Future `agent.*` manifests for Codex and runtime agents
+- Future capability, tool, model, runtime image, integration, and API manifests
+- Root/child project manifests discovered through mdkg capability search
+
+## Projection Targets
+
+- `.codex/agents` TOML
+- future runtime agent manifests
+- future workflow/runtime protocol resource and capability objects
+- future workflow/runtime protocol definitions
+
+## Open Questions
+
+- Which MANIFEST template families should be promoted into public seeded assets
+  first?
+- Which projection fields should be generated versus manually maintained?
+- What validation command should become the canonical MANIFEST template coverage
+  check?