mdkg 0.4.2 → 0.5.0

package/dist/graph/subgraphs.js

@@ -22,6 +22,131 @@ const MANIFEST_ENTRY = "manifest.json";
 const GLOBAL_INDEX_ENTRY = ".mdkg/index/global.json";
 const SKILLS_INDEX_ENTRY = ".mdkg/index/skills.json";
 const CAPABILITIES_INDEX_ENTRY = ".mdkg/index/capabilities.json";
+const REQUIRED_INDEX_ENTRIES = [GLOBAL_INDEX_ENTRY, SKILLS_INDEX_ENTRY, CAPABILITIES_INDEX_ENTRY];
+const SHA256_PATTERN = /^sha256:[a-f0-9]{64}$/;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireString(value, field) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`bundle manifest invalid: ${field} must be a non-empty string`);
+    return value;
+}
+function requireHash(value, field) {
+    const result = requireString(value, field);
+    if (!SHA256_PATTERN.test(result))
+        throw new Error(`bundle manifest invalid: ${field} must be a sha256 digest`);
+    return result;
+}
+function requireSafePath(value, field) {
+    const result = requireString(value, field).replace(/\\/g, "/");
+    if (path_1.default.posix.isAbsolute(result) || result.split("/").some((part) => part === "" || part === "." || part === "..")) {
+        throw new Error(`bundle manifest invalid: ${field} must be a safe relative path`);
+    }
+    return result;
+}
+function manifestFilesHash(files) {
+    const data = `${JSON.stringify(files.map((file) => ({
+        path: file.path,
+        kind: file.kind,
+        workspace: file.workspace,
+        visibility: file.visibility,
+        size: file.size,
+        sha256: file.sha256,
+    })), null, 2)}\n`;
+    return sha256Buffer(Buffer.from(data, "utf8"));
+}
+function validateForeignManifest(value) {
+    if (!isRecord(value))
+        throw new Error("bundle manifest invalid: root must be an object");
+    if (value.manifest_version !== 1 || value.tool !== "mdkg")
+        throw new Error("bundle manifest invalid: unsupported version or tool");
+    const mdkgVersion = requireString(value.mdkg_version, "mdkg_version");
+    if (value.profile !== "private" && value.profile !== "public")
+        throw new Error("bundle manifest invalid: profile must be private or public");
+    if (!Array.isArray(value.selected_workspaces) || value.selected_workspaces.length === 0) {
+        throw new Error("bundle manifest invalid: selected_workspaces must be a non-empty array");
+    }
+    const selectedWorkspaces = value.selected_workspaces.map((item, index) => requireString(item, `selected_workspaces[${index}]`));
+    if (new Set(selectedWorkspaces).size !== selectedWorkspaces.length)
+        throw new Error("bundle manifest invalid: duplicate selected workspace");
+    if (!isRecord(value.source))
+        throw new Error("bundle manifest invalid: source must be an object");
+    const repo = requireString(value.source.repo, "source.repo");
+    const gitHead = value.source.git_head;
+    if (gitHead !== null && (typeof gitHead !== "string" || !/^[a-f0-9]{40}$/.test(gitHead))) {
+        throw new Error("bundle manifest invalid: source.git_head must be null or a Git SHA");
+    }
+    if (typeof value.source.dirty !== "boolean")
+        throw new Error("bundle manifest invalid: source.dirty must be boolean");
+    if (!Number.isSafeInteger(value.file_count) || Number(value.file_count) < 0)
+        throw new Error("bundle manifest invalid: file_count");
+    if (!isRecord(value.index_hashes) || !Array.isArray(value.files))
+        throw new Error("bundle manifest invalid: indexes and files are required");
+    const indexHashes = {};
+    for (const [entryPath, hash] of Object.entries(value.index_hashes))
+        indexHashes[requireSafePath(entryPath, "index hash path")] = requireHash(hash, `index_hashes.${entryPath}`);
+    const seen = new Set();
+    const files = value.files.map((item, index) => {
+        if (!isRecord(item))
+            throw new Error(`bundle manifest invalid: files[${index}] must be an object`);
+        const filePath = requireSafePath(item.path, `files[${index}].path`);
+        if (seen.has(filePath))
+            throw new Error(`bundle manifest invalid: duplicate file ${filePath}`);
+        seen.add(filePath);
+        if (item.kind !== "authored" && item.kind !== "archive_cache" && item.kind !== "generated_index")
+            throw new Error(`bundle manifest invalid: files[${index}].kind`);
+        if (!Number.isSafeInteger(item.size) || Number(item.size) < 0)
+            throw new Error(`bundle manifest invalid: files[${index}].size`);
+        const workspace = item.workspace === undefined ? undefined : requireString(item.workspace, `files[${index}].workspace`);
+        if (item.visibility !== undefined && item.visibility !== "private" && item.visibility !== "internal" && item.visibility !== "public")
+            throw new Error(`bundle manifest invalid: files[${index}].visibility`);
+        return { path: filePath, kind: item.kind, size: Number(item.size), sha256: requireHash(item.sha256, `files[${index}].sha256`), ...(workspace ? { workspace } : {}), ...(item.visibility ? { visibility: item.visibility } : {}) };
+    });
+    if (Number(value.file_count) !== files.length)
+        throw new Error("bundle manifest invalid: file_count mismatch");
+    for (const required of REQUIRED_INDEX_ENTRIES) {
+        const row = files.find((file) => file.path === required);
+        if (!row || row.kind !== "generated_index" || row.sha256 !== indexHashes[required])
+            throw new Error(`bundle manifest invalid: required index contract mismatch for ${required}`);
+    }
+    return {
+        manifest_version: 1,
+        tool: "mdkg",
+        mdkg_version: mdkgVersion,
+        profile: value.profile,
+        selected_workspaces: selectedWorkspaces,
+        source: { repo, git_head: gitHead, dirty: value.source.dirty },
+        source_tree_hash: requireHash(value.source_tree_hash, "source_tree_hash"),
+        bundle_hash: requireHash(value.bundle_hash, "bundle_hash"),
+        file_count: files.length,
+        index_hashes: indexHashes,
+        files,
+    };
+}
+function validateIndexShape(value) {
+    if (!isRecord(value) || !isRecord(value.meta) || !isRecord(value.nodes) || !isRecord(value.reverse_edges) || !isRecord(value.workspaces)) {
+        throw new Error("generated global index has an invalid shape");
+    }
+    return value;
+}
+function publicProjectionErrors(index, manifest) {
+    if (manifest.profile !== "public")
+        return [];
+    const selected = new Set(manifest.selected_workspaces);
+    const rows = new Map(manifest.files.map((file) => [file.path, file]));
+    const errors = [];
+    for (const alias of Object.keys(index.workspaces)) {
+        if (!selected.has(alias))
+            errors.push(`public bundle contains unselected workspace ${alias}`);
+    }
+    for (const node of Object.values(index.nodes)) {
+        const row = rows.get(toPosixPath(node.path));
+        if (!selected.has(node.ws) || !row || row.visibility !== "public")
+            errors.push(`public bundle contains non-public node ${node.qid}`);
+    }
+    return errors;
+}
 function toPosixPath(value) {
     return value.split(path_1.default.sep).join("/");
 }
@@ -36,7 +161,7 @@ function readJsonEntry(entries, entryPath) {
     return JSON.parse(data.toString("utf8"));
 }
 function readBundleEntries(bundlePath) {
-    return new Map((0, zip_1.readZipEntries)(fs_1.default.readFileSync(bundlePath)).map((entry) => [entry.name, entry.data]));
+    return new Map((0, zip_1.readZipFileEntries)(bundlePath).map((entry) => [entry.name, entry.data]));
 }
 function resolveBundlePath(root, source) {
     return path_1.default.resolve(root, source.path);
@@ -126,6 +251,15 @@ function entryHashErrors(entries, manifest) {
             errors.push(`size mismatch for ${file.path}`);
         }
     }
+    for (const required of REQUIRED_INDEX_ENTRIES) {
+        const data = entries.get(required);
+        if (data && sha256Buffer(data) !== manifest.index_hashes[required])
+            errors.push(`generated index hash mismatch: ${required}`);
+    }
+    if (manifestFilesHash(manifest.files.filter((file) => file.kind !== "generated_index")) !== manifest.source_tree_hash)
+        errors.push("source_tree_hash mismatch");
+    if (manifestFilesHash(manifest.files) !== manifest.bundle_hash)
+        errors.push("bundle_hash mismatch");
     return errors;
 }
 function projectOneSource(root, subgraph, source) {
@@ -159,11 +293,14 @@ function projectOneSource(root, subgraph, source) {
             throw new Error(`bundle not found: ${source.path}`);
         }
         entries = readBundleEntries(bundlePath);
-        manifest = readJsonEntry(entries, MANIFEST_ENTRY);
-        index = readJsonEntry(entries, GLOBAL_INDEX_ENTRY);
-        readJsonEntry(entries, SKILLS_INDEX_ENTRY);
-        readJsonEntry(entries, CAPABILITIES_INDEX_ENTRY);
+        manifest = validateForeignManifest(readJsonEntry(entries, MANIFEST_ENTRY));
+        index = validateIndexShape(readJsonEntry(entries, GLOBAL_INDEX_ENTRY));
+        if (!isRecord(readJsonEntry(entries, SKILLS_INDEX_ENTRY)))
+            throw new Error("generated skills index has an invalid shape");
+        if (!isRecord(readJsonEntry(entries, CAPABILITIES_INDEX_ENTRY)))
+            throw new Error("generated capabilities index has an invalid shape");
         errors.push(...entryHashErrors(entries, manifest));
+        errors.push(...publicProjectionErrors(index, manifest));
         if (manifest.profile !== source.expected_profile) {
             errors.push(`expected ${source.expected_profile} bundle but found ${manifest.profile}`);
         }

package/dist/graph/validate_graph.js

@@ -6,6 +6,7 @@ const agent_file_types_1 = require("./agent_file_types");
 const refs_1 = require("../util/refs");
 const qid_1 = require("../util/qid");
 const goal_scope_1 = require("./goal_scope");
+const loop_bindings_1 = require("./loop_bindings");
 function pushError(errors, message) {
     if (errors) {
         errors.push(message);
@@ -337,12 +338,11 @@ function validateAgentWorkflowDisputeRefs(index, allowMissing, externalWorkspace
     }
 }
 function buildNodeIdsByWorkspace(index) {
-    const nodeIdsByWorkspace = {};
+    const nodeIdsByWorkspace = new Map();
     for (const node of Object.values(index.nodes)) {
-        if (!nodeIdsByWorkspace[node.ws]) {
-            nodeIdsByWorkspace[node.ws] = new Set();
-        }
-        nodeIdsByWorkspace[node.ws].add(node.id);
+        const ids = nodeIdsByWorkspace.get(node.ws) ?? new Set();
+        ids.add(node.id);
+        nodeIdsByWorkspace.set(node.ws, ids);
     }
     return nodeIdsByWorkspace;
 }
@@ -351,10 +351,10 @@ function validateAgentWorkflowNodeIdRef(qid, ws, field, value, nodeIdsByWorkspac
     if (workspace && value.includes(":") && externalWorkspaces?.has(workspace)) {
         return;
     }
-    if (value.includes(":") && nodeIdsByWorkspace[workspace]?.has(value.split(":").slice(1).join(":"))) {
+    if (value.includes(":") && nodeIdsByWorkspace.get(workspace)?.has(value.split(":").slice(1).join(":"))) {
         return;
     }
-    if (nodeIdsByWorkspace[ws]?.has(value)) {
+    if (nodeIdsByWorkspace.get(ws)?.has(value)) {
         return;
     }
     if (allowSkillRef &&
@@ -393,15 +393,14 @@ function validateAgentWorkflowFeedbackProposalRefs(index, allowMissing, knownSki
     }
 }
 function buildArchiveIdsByWorkspace(index) {
-    const archiveIdsByWorkspace = {};
+    const archiveIdsByWorkspace = new Map();
     for (const node of Object.values(index.nodes)) {
         if (node.type !== "archive") {
             continue;
         }
-        if (!archiveIdsByWorkspace[node.ws]) {
-            archiveIdsByWorkspace[node.ws] = new Set();
-        }
-        archiveIdsByWorkspace[node.ws].add(node.id);
+        const ids = archiveIdsByWorkspace.get(node.ws) ?? new Set();
+        ids.add(node.id);
+        archiveIdsByWorkspace.set(node.ws, ids);
     }
     return archiveIdsByWorkspace;
 }
@@ -414,7 +413,7 @@ function validateArchiveUriValue(qid, ws, field, value, archiveIdsByWorkspace, a
         pushError(errors, `${qid}: ${field} has malformed archive ref ${value}`);
         return;
     }
-    if (archiveIdsByWorkspace[ws]?.has(archiveId)) {
+    if (archiveIdsByWorkspace.get(ws)?.has(archiveId)) {
         return;
     }
     if (allowMissing) {
@@ -496,6 +495,102 @@ function validateGoalRefs(index, allowMissing, errors) {
         }
     }
 }
+function loopAttributeList(node, key) {
+    const value = node.attributes[key];
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function resolveLoopEvidenceNode(index, ws, ref) {
+    const resolved = (0, qid_1.resolveQid)(index, ref, ws);
+    return resolved.status === "ok" ? index.nodes[resolved.qid] : undefined;
+}
+function isAcceptedLoopDecision(node) {
+    return node.type === "dec" && node.status === "accepted";
+}
+function isVerifiedLoopApproval(node) {
+    if (node.type === "dec") {
+        return node.status === "accepted";
+    }
+    if (node.type === "checkpoint") {
+        return node.status === "done";
+    }
+    return node.type === "receipt" && node.attributes.receipt_status === "verified";
+}
+function validateLoopTypedRefs(index, allowMissing, errors) {
+    for (const [qid, node] of Object.entries(index.nodes)) {
+        if (node.type !== "loop") {
+            continue;
+        }
+        for (const ref of loopAttributeList(node, "decision_refs")) {
+            if ((0, refs_1.isUriRef)(ref)) {
+                pushError(errors, `${qid}: decision_refs requires a local accepted dec ref, got ${ref}`);
+                continue;
+            }
+            const target = resolveLoopEvidenceNode(index, node.ws, ref);
+            if (!target) {
+                if (!allowMissing) {
+                    pushError(errors, `${qid}: decision_refs references missing node ${ref}`);
+                }
+                continue;
+            }
+            if (!isAcceptedLoopDecision(target)) {
+                pushError(errors, `${qid}: decision_refs ${ref} must target an accepted dec, got ${target.type}:${target.status ?? "none"}`);
+            }
+        }
+        for (const ref of loopAttributeList(node, "approval_refs")) {
+            if ((0, refs_1.isUriRef)(ref)) {
+                continue;
+            }
+            const target = resolveLoopEvidenceNode(index, node.ws, ref);
+            if (!target) {
+                if (!allowMissing) {
+                    pushError(errors, `${qid}: approval_refs references missing node ${ref}`);
+                }
+                continue;
+            }
+            if (!isVerifiedLoopApproval(target)) {
+                pushError(errors, `${qid}: approval_refs ${ref} must target an accepted dec, done checkpoint, or verified receipt, got ${target.type}:${target.status ?? target.attributes.receipt_status ?? "none"}`);
+            }
+        }
+        const checks = [
+            { key: "question_answer_refs", kind: "decision" },
+            { key: "action_approval_refs", kind: "approval" },
+            { key: "evidence_lane_refs", kind: "evidence" },
+            { key: "lane_waiver_decision_refs", kind: "decision" },
+            { key: "lane_waiver_approval_refs", kind: "approval" },
+        ];
+        for (const check of checks) {
+            const bindings = (0, loop_bindings_1.parseLoopRefBindings)(loopAttributeList(node, check.key));
+            for (const binding of bindings) {
+                if ((0, refs_1.isUriRef)(binding.ref)) {
+                    if (check.kind === "decision") {
+                        pushError(errors, `${qid}: ${check.key} ${binding.identity} requires a local accepted dec ref, got ${binding.ref}`);
+                    }
+                    continue;
+                }
+                const target = resolveLoopEvidenceNode(index, node.ws, binding.ref);
+                if (!target) {
+                    if (!allowMissing) {
+                        pushError(errors, `${qid}: ${check.key} ${binding.identity} references missing node ${binding.ref}`);
+                    }
+                    continue;
+                }
+                if (check.kind === "decision" && !isAcceptedLoopDecision(target)) {
+                    pushError(errors, `${qid}: ${check.key} ${binding.identity} must target an accepted dec`);
+                }
+                if (check.kind === "approval" && !isVerifiedLoopApproval(target)) {
+                    pushError(errors, `${qid}: ${check.key} ${binding.identity} must target an accepted dec, done checkpoint, or verified receipt`);
+                }
+            }
+        }
+        const waiverDecisionIdentities = new Set((0, loop_bindings_1.parseLoopRefBindings)(loopAttributeList(node, "lane_waiver_decision_refs")).map((binding) => binding.identity));
+        const waiverApprovalIdentities = new Set((0, loop_bindings_1.parseLoopRefBindings)(loopAttributeList(node, "lane_waiver_approval_refs")).map((binding) => binding.identity));
+        for (const identity of new Set([...waiverDecisionIdentities, ...waiverApprovalIdentities])) {
+            if (!waiverDecisionIdentities.has(identity) || !waiverApprovalIdentities.has(identity)) {
+                pushError(errors, `${qid}: lane waiver ${identity} requires both decision and approval bindings`);
+            }
+        }
+    }
+}
 function validateSingleActiveRootGoals(index, errors) {
     const activeByWorkspace = {};
     for (const [qid, node] of Object.entries(index.nodes)) {
@@ -563,6 +658,7 @@ function collectGraphErrors(index, options = {}) {
     validateAgentWorkflowDisputeRefs(index, allowMissing, externalWorkspaces, errors);
     validateAgentWorkflowFeedbackProposalRefs(index, allowMissing, knownSkillSlugs, externalWorkspaces, errors);
     validateArchiveUriRefs(index, allowMissing, errors);
+    validateLoopTypedRefs(index, allowMissing, errors);
     validateGoalRefs(index, allowMissing, errors);
     validateSingleActiveRootGoals(index, errors);
     detectPrevNextCycles(index, errors);

package/dist/graph/workspace_files.js

@@ -8,28 +8,51 @@ exports.listWorkspaceDocFiles = listWorkspaceDocFiles;
 exports.listWorkspaceDocFilesByAlias = listWorkspaceDocFilesByAlias;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const filesystem_authority_1 = require("../core/filesystem_authority");
+const workspace_path_1 = require("../core/workspace_path");
 const DOC_FOLDERS = ["core", "design", "work"];
-function listMarkdownFiles(dir) {
+function accountMarkdownFile(filePath, budget) {
+    const size = fs_1.default.statSync(filePath).size;
+    if (size > budget.limits.max_file_bytes) {
+        throw new Error(`graph file exceeds index.limits.max_file_bytes (${budget.limits.max_file_bytes}): ${filePath}`);
+    }
+    if (budget.files + 1 > budget.limits.max_files) {
+        throw new Error(`graph file count exceeds index.limits.max_files (${budget.limits.max_files})`);
+    }
+    if (budget.bytes + size > budget.limits.max_total_bytes) {
+        throw new Error(`graph bytes exceed index.limits.max_total_bytes (${budget.limits.max_total_bytes})`);
+    }
+    budget.files += 1;
+    budget.bytes += size;
+}
+function listMarkdownFiles(dir, budget, depth = 0) {
     if (!fs_1.default.existsSync(dir)) {
         return [];
     }
+    if (depth > budget.limits.max_depth) {
+        throw new Error(`graph directory depth exceeds index.limits.max_depth (${budget.limits.max_depth}): ${dir}`);
+    }
     const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
     const files = [];
     for (const entry of entries) {
         const fullPath = path_1.default.join(dir, entry.name);
         if (entry.isDirectory()) {
-            files.push(...listMarkdownFiles(fullPath));
+            files.push(...listMarkdownFiles(fullPath, budget, depth + 1));
         }
         else if (entry.isFile() && entry.name.endsWith(".md")) {
+            accountMarkdownFile(fullPath, budget);
             files.push(fullPath);
         }
     }
     return files;
 }
-function listArchiveSidecarFiles(dir) {
+function listArchiveSidecarFiles(dir, budget, depth = 0) {
     if (!fs_1.default.existsSync(dir)) {
         return [];
     }
+    if (depth > budget.limits.max_depth) {
+        throw new Error(`graph directory depth exceeds index.limits.max_depth (${budget.limits.max_depth}): ${dir}`);
+    }
     const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
     const files = [];
     for (const entry of entries) {
@@ -38,9 +61,10 @@ function listArchiveSidecarFiles(dir) {
         }
         const fullPath = path_1.default.join(dir, entry.name);
         if (entry.isDirectory()) {
-            files.push(...listArchiveSidecarFiles(fullPath));
+            files.push(...listArchiveSidecarFiles(fullPath, budget, depth + 1));
         }
         else if (entry.isFile() && entry.name.endsWith(".md")) {
+            accountMarkdownFile(fullPath, budget);
             files.push(fullPath);
         }
     }
@@ -54,31 +78,37 @@ function getWorkspaceDocRoots(root, config) {
         if (!entry.enabled) {
             continue;
         }
-        const wsRoot = path_1.default.resolve(root, entry.path, entry.mdkg_dir);
+        const wsRoot = (0, filesystem_authority_1.withContainedPathSink)({
+            root,
+            relativePath: (0, workspace_path_1.workspaceDocumentRelativePath)(entry.path, entry.mdkg_dir),
+            operation: "read",
+        }, ({ absolutePath }) => absolutePath);
         roots.push({ alias, root: wsRoot });
     }
     return roots;
 }
 function listWorkspaceDocFiles(root, config) {
     const files = [];
+    const budget = { files: 0, bytes: 0, limits: config.index.limits };
     for (const { root: wsRoot } of getWorkspaceDocRoots(root, config)) {
         for (const folder of DOC_FOLDERS) {
             const folderPath = path_1.default.join(wsRoot, folder);
-            files.push(...listMarkdownFiles(folderPath));
+            files.push(...listMarkdownFiles(folderPath, budget));
         }
-        files.push(...listArchiveSidecarFiles(path_1.default.join(wsRoot, "archive")));
+        files.push(...listArchiveSidecarFiles(path_1.default.join(wsRoot, "archive"), budget));
     }
     return files;
 }
 function listWorkspaceDocFilesByAlias(root, config) {
     const result = {};
+    const budget = { files: 0, bytes: 0, limits: config.index.limits };
     for (const { alias, root: wsRoot } of getWorkspaceDocRoots(root, config)) {
         const files = [];
         for (const folder of DOC_FOLDERS) {
             const folderPath = path_1.default.join(wsRoot, folder);
-            files.push(...listMarkdownFiles(folderPath));
+            files.push(...listMarkdownFiles(folderPath, budget));
         }
-        files.push(...listArchiveSidecarFiles(path_1.default.join(wsRoot, "archive")));
+        files.push(...listArchiveSidecarFiles(path_1.default.join(wsRoot, "archive"), budget));
         files.sort();
         result[alias] = files;
     }

package/dist/init/AGENT_START.md

@@ -28,6 +28,11 @@ Agent operating prompt:
 - 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.
+- Use `mdkg loop show <loop>`, `mdkg loop plan <loop>`, and
+  `mdkg pack <loop>` for first-class loop nodes. Use
+  `mdkg skill show pursue-mdkg-loop` before executing a loop so the agent works
+  every authorized linked lane, records blocker recovery, and closes only when
+  the loop definition of done is satisfied or explicitly waived.
 - Record skill improvement candidates during normal goal execution; edit `SKILL.md` only when the active node is explicit skill-maintenance work.
 - Use `mdkg skill list`, `mdkg skill search`, and `mdkg skill show <slug>` for skill discovery.
 - Use `mdkg capability list/search/show` for deterministic skills, `MANIFEST.md` / legacy `SPEC.md`, `WORK.md`, core-doc, and design-doc capability discovery.
@@ -97,6 +102,16 @@ If an active goal is known:
 - `mdkg goal evaluate <goal-id>`
 - repeat until the goal condition is achieved, blocked, paused, or budget-limited
 
+If an active loop is known:
+- `mdkg loop show <loop-id> --json`
+- `mdkg skill show pursue-mdkg-loop`
+- `mdkg loop plan <loop-id> --json`
+- `mdkg pack <loop-id> --pack-profile concise --dry-run --stats`
+- answer or record pre-run questions and approval requirements
+- work every authorized linked lane before marking the loop done or blocked
+- keep the loop open while required lanes are incomplete and not explicitly
+  waived
+
 If no task is known:
 - `mdkg search "..."`
 - `mdkg show <id>`
@@ -113,6 +128,7 @@ Skill discovery:
 - `mdkg skill list --tags stage:execute --json`
 - `mdkg skill list --tags stage:review --json`
 - `mdkg skill show select-work-and-ground-context`
+- `mdkg skill show pursue-mdkg-loop`
 
 Capability discovery:
 - `mdkg capability list --kind skill --json`

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -29,6 +29,7 @@ Primary commands:
 - `mdkg subgraph`
 - `mdkg work`
 - `mdkg goal`
+- `mdkg loop`
 - `mdkg task`
 - `mdkg validate`
 - `mdkg status [--json]`
@@ -130,6 +131,7 @@ Validation commands:
 Node creation commands:
 - `mdkg new <type> "<title>" [options] [--json]`
 - `mdkg new goal "<title>" [options] [--json]`
+- `mdkg new loop "<title>" [options] [--json]`
 - `mdkg new spike "<research question>" [options] [--json]`
 
 Agent workflow file type creation:
@@ -153,10 +155,22 @@ Agent workflow notes:
 - `manifest` and `work` scaffold as validation-clean standalone docs.
 - `work_order`, `receipt`, `feedback`, `dispute`, and `proposal` need real refs before strict `mdkg validate` passes.
 - `goal` nodes capture recursive objective state and required checks, but normal `mdkg next` does not select them.
+- `loop` nodes capture reusable process state, fork lineage, child refs, run/evidence refs, blocker-continuation policy, and a high-bar definition of done; runtime execution remains outside mdkg.
 - `spike` nodes are actionable research/planning work under `.mdkg/work/`; use `mdkg task start|update|done` for lifecycle state.
 - Spikes record sources, findings, recommendations, follow-up node ideas, and skill candidates in Markdown body sections; they do not perform web search, execute research, create follow-up nodes, generate `SKILL.md`, or expose a `mdkg spike ...` namespace automatically.
 - after fresh init, run `mdkg index` before treating `mdkg doctor --strict --json` as a clean health gate; init writes source scaffold files and index writes generated caches.
 
+Loop commands:
+- `mdkg loop list [--json]`
+- `mdkg loop show <loop-or-template> [--json]`
+- `mdkg loop fork <template> --scope <scope> [--materialization default_children|planning_only|manual] [--planning-only] [--no-children] [--dry-run] [--json]`
+- `mdkg loop plan <loop> [--json]`
+- `mdkg loop next <loop> [--json]`
+- `mdkg loop runs <loop> [--json]`
+- `loop` is one first-class node type; templates, scoped forks, and run-bearing loops are represented through metadata and links
+- seed templates live under `.mdkg/templates/loops/*.loop.md`
+- mdkg defines durable declarative process state and graph context; runtimes execute agents, tools, sandboxes, traces, and model routing
+
 Workspace registry commands:
 - `mdkg workspace ls [--json]`
 - `mdkg workspace add <alias> <path> [--mdkg-dir <dir>] [--visibility <level>] [--json]`

package/dist/init/config.json

@@ -12,7 +12,13 @@
     "global_index_path": ".mdkg/index/global.json",
     "sqlite_path": ".mdkg/index/mdkg.sqlite",
     "sqlite_commit_warning_bytes": 52428800,
-    "lock_timeout_ms": 10000
+    "lock_timeout_ms": 10000,
+    "limits": {
+      "max_files": 100000,
+      "max_file_bytes": 8388608,
+      "max_total_bytes": 536870912,
+      "max_depth": 64
+    }
   },
   "capabilities": {
     "cache_path": ".mdkg/index/capabilities.json"

package/dist/init/init-manifest.json

@@ -1,12 +1,12 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.4.2",
+  "mdkg_version": "0.5.0",
   "files": [
     {
       "path": ".mdkg/config.json",
       "category": "config",
-      "sha256": "715e2f55843dc31f66d4b7d333b5f89ea2aeeacc30f5dfaf7d3fd9f2c41e5fb0"
+      "sha256": "3d0ed0f8d65a33fe54a3855b3314a6762ad6dd1eaf6efcdce3e551a493433dc3"
     },
     {
       "path": ".mdkg/core/COLLABORATION.md",
@@ -83,6 +83,11 @@
       "category": "default_skill",
       "sha256": "0545b011232d6924d84d80ad4b33153e591249d440c55481f125b37923c298d5"
     },
+    {
+      "path": ".mdkg/skills/pursue-mdkg-loop/SKILL.md",
+      "category": "default_skill",
+      "sha256": "65dae2a6e79f2f7e4265b7057287db0308ac6ac59e6ebe9a6b6cd50b5d90176b"
+    },
     {
       "path": ".mdkg/skills/select-work-and-ground-context/SKILL.md",
       "category": "default_skill",
@@ -143,6 +148,11 @@
       "category": "template",
       "sha256": "8f984580aefd02b34639fa7f5d2a834662656bbf2e12f14a285f5ae31aff74ce"
     },
+    {
+      "path": ".mdkg/templates/default/loop.md",
+      "category": "template",
+      "sha256": "6e8f280c3375b9ec18e09fdb263665b2e3da45ca09b2547378fdd4c9bc015d89"
+    },
     {
       "path": ".mdkg/templates/default/manifest.md",
       "category": "template",
@@ -203,6 +213,41 @@
       "category": "template",
       "sha256": "1ab3c4c79ecdaff2b76007bfbb9844bf581da592f70ac2a2475594b9c279d7cd"
     },
+    {
+      "path": ".mdkg/templates/loops/backend-api-cli-bloat-audit.loop.md",
+      "category": "template",
+      "sha256": "e61083901ae2dcd315eba81ebf9aa90b9cbe7fb3ba923dd6834feb5502fd03b3"
+    },
+    {
+      "path": ".mdkg/templates/loops/design-frontend-ux-audit.loop.md",
+      "category": "template",
+      "sha256": "2da3ad70d71e52545006883452b5fc2673761ecd0875a00746a5468c25eee241"
+    },
+    {
+      "path": ".mdkg/templates/loops/duplicate-code-and-linting-audit.loop.md",
+      "category": "template",
+      "sha256": "36cbe0957883b5d75ebae6705f24eeb77f616202553c428386eeba9821aeaccc"
+    },
+    {
+      "path": ".mdkg/templates/loops/security-audit.loop.md",
+      "category": "template",
+      "sha256": "2c26211f628cd62474595191fdc106e051a839bf7232a2336852a1b44e1ca9ba"
+    },
+    {
+      "path": ".mdkg/templates/loops/tech-stack-best-practices-audit.loop.md",
+      "category": "template",
+      "sha256": "866c6aae55fa1e1eba9b77c0c92b678c779d96eb39cf293cf51c7a244ea39e54"
+    },
+    {
+      "path": ".mdkg/templates/loops/test-ci-skill-infrastructure-audit.loop.md",
+      "category": "template",
+      "sha256": "84d12faf4c33d808eae229f13f169f5b1aedd199e9ef5ef3f1b4b055f0fb3c39"
+    },
+    {
+      "path": ".mdkg/templates/loops/user-story-audit-and-recommendations.loop.md",
+      "category": "template",
+      "sha256": "2bc4b328ccdfd5c0959b003956a5b8bff1ba83032514ed23025fc8f3587c323f"
+    },
     {
       "path": ".mdkg/templates/skills/base.SKILL.md",
       "category": "template",
@@ -311,7 +356,7 @@
     {
       "path": "AGENT_START.md",
       "category": "startup_doc",
-      "sha256": "c387ce4fee55eafca09bcd30f32e4d7dc8ee7f9cc9811c1adffa0756c9423a35"
+      "sha256": "60d5133337d383b0a6a13e108d26a6e034afe59f21a27318cf6f8f0cc3c3c5a3"
     },
     {
       "path": "AGENTS.md",
@@ -326,7 +371,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "7a71fa553e38395caae5f18ecb9650911c56a019b25e793addc20701e5df5a9e"
+      "sha256": "b055b6e1a36f633ccb7eb9954f3ba4ec93d57b0829fcfcbdbc1713885d6bc357"
     },
     {
       "path": "llms.txt",