mdkg 0.4.2 → 0.5.0

package/dist/core/project_db_snapshot.js

@@ -7,12 +7,12 @@ exports.resolveContainedProjectDbPath = resolveContainedProjectDbPath;
 exports.sealProjectDbSnapshot = sealProjectDbSnapshot;
 exports.verifyProjectDbSnapshot = verifyProjectDbSnapshot;
 exports.projectDbSnapshotStatus = projectDbSnapshotStatus;
-exports.canonicalDumpForSnapshot = canonicalDumpForSnapshot;
 exports.dumpProjectDbSnapshot = dumpProjectDbSnapshot;
 exports.diffProjectDbSnapshots = diffProjectDbSnapshots;
 const crypto_1 = __importDefault(require("crypto"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const filesystem_authority_1 = require("./filesystem_authority");
 const project_db_1 = require("./project_db");
 const version_1 = require("./version");
 const atomic_1 = require("../util/atomic");
@@ -166,7 +166,11 @@ function readManifest(filePath) {
         typeof manifest.snapshot_sha256 !== "string" ||
         typeof manifest.byte_size !== "number" ||
         !Array.isArray(manifest.table_counts) ||
-        !Array.isArray(manifest.migrations)) {
+        !Array.isArray(manifest.migrations) ||
+        (manifest.queue_policy !== "drain" && manifest.queue_policy !== "paused") ||
+        typeof manifest.queue_summary !== "object" ||
+        manifest.queue_summary === null ||
+        Array.isArray(manifest.queue_summary)) {
         throw new errors_1.ValidationError("snapshot manifest has unsupported shape");
     }
     return manifest;
@@ -251,7 +255,9 @@ function sealProjectDbSnapshot(root, config, queuePolicy = "drain") {
     }
     try {
         const runtimeHash = sha256File(layout.runtimeFile);
-        const manifest = buildManifest(root, config, tempSnapshot, runtimeHash, queuePolicy, queueSummary);
+        const sealedQueueSummary = (0, project_db_queue_1.readProjectQueueSnapshotSummary)(tempSnapshot);
+        assertQueueSnapshotPolicy(queuePolicy, sealedQueueSummary);
+        const manifest = buildManifest(root, config, tempSnapshot, runtimeHash, queuePolicy, sealedQueueSummary);
         (0, atomic_1.atomicWriteFile)(tempManifest, `${JSON.stringify(manifest, null, 2)}\n`);
         fs_1.default.renameSync(tempSnapshot, layout.stateFile);
         fs_1.default.renameSync(tempManifest, layout.stateManifest);
@@ -267,7 +273,7 @@ function sealProjectDbSnapshot(root, config, queuePolicy = "drain") {
             table_counts: manifest.table_counts,
             migrations: manifest.migrations,
             queue_policy: queuePolicy,
-            queue_summary: queueSummary,
+            queue_summary: sealedQueueSummary,
             warnings: warningListFromVerify(root, config),
         };
     }
@@ -384,7 +390,18 @@ function verifyProjectDbSnapshot(root, config) {
                 warnings: [],
             });
         }
-        if (manifest.source_runtime_sha256 && fs_1.default.existsSync(layout.runtimeFile)) {
+        if (fs_1.default.existsSync(layout.runtimeFile) && !manifest.source_runtime_sha256) {
+            checks.push({
+                name: "runtime-freshness",
+                ok: false,
+                level: "fail",
+                path: rel(root, layout.runtimeFile),
+                detail: "snapshot source runtime hash is missing",
+                errors: ["snapshot manifest must include source_runtime_sha256 when the runtime database exists"],
+                warnings: [],
+            });
+        }
+        else if (manifest.source_runtime_sha256 && fs_1.default.existsSync(layout.runtimeFile)) {
             const runtimeHash = sha256File(layout.runtimeFile);
             checks.push({
                 name: "runtime-freshness",
@@ -396,6 +413,30 @@ function verifyProjectDbSnapshot(root, config) {
                 warnings: runtimeHash === manifest.source_runtime_sha256 ? [] : ["runtime database hash differs from sealed snapshot source hash"],
             });
         }
+        try {
+            const sealedQueueSummary = (0, project_db_queue_1.readProjectQueueSnapshotSummary)(layout.stateFile);
+            assertQueueSnapshotPolicy(manifest.queue_policy, sealedQueueSummary);
+            const matchesManifest = compareJson(sealedQueueSummary, manifest.queue_summary);
+            checks.push({
+                name: "queue-policy",
+                ok: matchesManifest,
+                level: matchesManifest ? "ok" : "fail",
+                detail: matchesManifest ? "sealed queue state satisfies policy and matches manifest" : "sealed queue summary differs from manifest",
+                errors: matchesManifest ? [] : ["sealed queue summary does not match snapshot manifest"],
+                warnings: [],
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            checks.push({
+                name: "queue-policy",
+                ok: false,
+                level: "fail",
+                detail: "sealed queue state violates snapshot policy",
+                errors: [message],
+                warnings: [],
+            });
+        }
     }
     const errors = checks.flatMap((check) => check.errors.map((error) => `${check.name}: ${error}`));
     const warnings = checks.flatMap((check) => check.warnings.map((warning) => `${check.name}: ${warning}`));
@@ -485,17 +526,24 @@ function canonicalDumpForSnapshot(root, snapshotPath) {
         db.close();
     }
 }
+function canonicalDumpForContainedSnapshot(root, rawPath, label) {
+    const resolved = resolveContainedProjectDbPath(root, rawPath, label);
+    const relativePath = rel(root, resolved);
+    return (0, filesystem_authority_1.withContainedPathSink)({ root, relativePath, operation: "read" }, ({ absolutePath }) => ({
+        absolutePath,
+        dump: canonicalDumpForSnapshot(root, absolutePath),
+    }));
+}
 function dumpProjectDbSnapshot(root, config, snapshotPath, outputPath) {
     const layout = (0, project_db_1.resolveConfiguredProjectDbLayout)(root, config.db);
-    const resolvedSnapshot = snapshotPath
-        ? resolveContainedProjectDbPath(root, snapshotPath, "--snapshot")
-        : layout.stateFile;
-    const dump = canonicalDumpForSnapshot(root, resolvedSnapshot);
+    const snapshot = canonicalDumpForContainedSnapshot(root, snapshotPath ?? layout.stateFile, "--snapshot");
+    const resolvedSnapshot = snapshot.absolutePath;
+    const dump = snapshot.dump;
     const dumpHash = sha256Buffer(dump);
     let output = null;
     if (outputPath) {
         const resolvedOutput = resolveContainedProjectDbPath(root, outputPath, "--output");
-        (0, atomic_1.atomicWriteFile)(resolvedOutput, dump);
+        (0, filesystem_authority_1.atomicReplaceContainedFile)({ root, relativePath: rel(root, resolvedOutput) }, dump);
         output = rel(root, resolvedOutput);
     }
     return {
@@ -509,10 +557,12 @@ function dumpProjectDbSnapshot(root, config, snapshotPath, outputPath) {
     };
 }
 function diffProjectDbSnapshots(root, leftPath, rightPath) {
-    const left = resolveContainedProjectDbPath(root, leftPath, "left snapshot");
-    const right = resolveContainedProjectDbPath(root, rightPath, "right snapshot");
-    const leftDump = canonicalDumpForSnapshot(root, left);
-    const rightDump = canonicalDumpForSnapshot(root, right);
+    const leftSnapshot = canonicalDumpForContainedSnapshot(root, leftPath, "left snapshot");
+    const rightSnapshot = canonicalDumpForContainedSnapshot(root, rightPath, "right snapshot");
+    const left = leftSnapshot.absolutePath;
+    const right = rightSnapshot.absolutePath;
+    const leftDump = leftSnapshot.dump;
+    const rightDump = rightSnapshot.dump;
     const leftLines = leftDump.trimEnd().split("\n");
     const rightLines = rightDump.trimEnd().split("\n");
     const leftSet = new Set(leftLines);

package/dist/core/workspace_path.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeContainedWorkspacePath = normalizeContainedWorkspacePath;
 exports.isRootWorkspacePath = isRootWorkspacePath;
 exports.workspaceDocumentRootKey = workspaceDocumentRootKey;
+exports.workspaceDocumentRelativePath = workspaceDocumentRelativePath;
 const path_1 = __importDefault(require("path"));
 function isAbsoluteOnSupportedPlatform(value) {
     return path_1.default.isAbsolute(value) || path_1.default.posix.isAbsolute(value) || path_1.default.win32.isAbsolute(value);
@@ -39,3 +40,9 @@ function workspaceDocumentRootKey(workspacePath, mdkgDir) {
         .filter((part) => part && part !== ".")
         .join("/");
 }
+function workspaceDocumentRelativePath(workspacePath, mdkgDir, ...suffix) {
+    return [workspacePath, mdkgDir, ...suffix]
+        .flatMap((value) => value.trim().split(/[\\/]+/))
+        .filter((part) => part && part !== ".")
+        .join("/");
+}

package/dist/graph/archive_integrity.js

@@ -36,7 +36,7 @@ function checkArchiveIntegrity(options) {
             result.errors.push(`compressed_sha256 mismatch: ${actualCompressedHash}`);
         }
         try {
-            const unzipped = (0, zip_1.readSingleFileZip)(fs_1.default.readFileSync(options.zipPath));
+            const unzipped = (0, zip_1.readSingleFileZipPath)(options.zipPath);
             const unzippedHash = hashArchiveBuffer(unzipped.data);
             if (unzippedHash !== options.expectedRawHash) {
                 result.errors.push(`zip payload sha256 mismatch: ${unzippedHash}`);

package/dist/graph/capabilities_index_cache.js

@@ -82,6 +82,7 @@ function writeCapabilitiesIndex(indexPath, index) {
 function loadCapabilitiesIndex(options) {
     const useCache = options.useCache ?? true;
     const allowReindex = options.allowReindex ?? options.config.index.auto_reindex;
+    const persistReindex = options.persistReindex ?? true;
     const indexPath = (0, capabilities_indexer_1.resolveCapabilitiesIndexPath)(options.root, options.config);
     if (!useCache) {
         const index = (0, capabilities_indexer_1.buildCapabilitiesIndex)(options.root, options.config);
@@ -93,7 +94,9 @@ function loadCapabilitiesIndex(options) {
     }
     if (allowReindex) {
         const index = (0, capabilities_indexer_1.buildCapabilitiesIndex)(options.root, options.config);
-        writeCapabilitiesIndex(indexPath, index);
+        if (persistReindex) {
+            writeCapabilitiesIndex(indexPath, index);
+        }
         return { index, rebuilt: true, stale };
     }
     if (fs_1.default.existsSync(indexPath)) {

package/dist/graph/frontmatter.js

@@ -4,6 +4,9 @@ exports.DEFAULT_FRONTMATTER_KEY_ORDER = void 0;
 exports.parseFrontmatter = parseFrontmatter;
 exports.formatFrontmatter = formatFrontmatter;
 const KEY_RE = /^[a-z][a-z0-9_]*$/;
+const MAX_FRONTMATTER_LINES = 1000;
+const MAX_FRONTMATTER_LINE_BYTES = 64 * 1024;
+const MAX_FRONTMATTER_LIST_ITEMS = 10000;
 exports.DEFAULT_FRONTMATTER_KEY_ORDER = [
     "id",
     "type",
@@ -20,6 +23,32 @@ exports.DEFAULT_FRONTMATTER_KEY_ORDER = [
     "required_checks",
     "max_iterations",
     "blocked_after_attempts",
+    "loop_mode",
+    "loop_role",
+    "scope_description",
+    "template_refs",
+    "materialization_mode",
+    "child_refs",
+    "pre_run_questions",
+    "question_answer_refs",
+    "pre_approved_actions",
+    "approval_gated_actions",
+    "required_actions",
+    "requested_actions",
+    "prohibited_actions",
+    "action_approval_refs",
+    "evidence_lanes",
+    "evidence_lane_refs",
+    "lane_waiver_refs",
+    "lane_waiver_decision_refs",
+    "lane_waiver_approval_refs",
+    "run_refs",
+    "decision_refs",
+    "output_refs",
+    "approval_refs",
+    "evaluation_refs",
+    "definition_of_done",
+    "blocker_policy",
     "epic",
     "parent",
     "prev",
@@ -116,6 +145,9 @@ function parseList(valueRaw, filePath, lineNumber) {
         return [];
     }
     const parts = inner.split(",");
+    if (parts.length > MAX_FRONTMATTER_LIST_ITEMS) {
+        throw formatError(filePath, lineNumber, `list exceeds ${MAX_FRONTMATTER_LIST_ITEMS} items`);
+    }
     const items = [];
     for (let i = 0; i < parts.length; i += 1) {
         const item = parts[i].trim();
@@ -156,10 +188,16 @@ function parseFrontmatter(content, filePath) {
     if (endIndex === -1) {
         throw formatError(filePath, 1, "frontmatter closing --- not found");
     }
+    if (endIndex > MAX_FRONTMATTER_LINES) {
+        throw formatError(filePath, 1, `frontmatter exceeds ${MAX_FRONTMATTER_LINES} lines`);
+    }
     const frontmatter = {};
     for (let i = 1; i < endIndex; i += 1) {
         const line = lines[i];
         const lineNumber = i + 1;
+        if (Buffer.byteLength(line, "utf8") > MAX_FRONTMATTER_LINE_BYTES) {
+            throw formatError(filePath, lineNumber, `frontmatter line exceeds ${MAX_FRONTMATTER_LINE_BYTES} bytes`);
+        }
         if (line.trim().length === 0) {
             throw formatError(filePath, lineNumber, "frontmatter lines must not be blank");
         }

package/dist/graph/goal_scope.js

@@ -4,7 +4,7 @@ exports.GOAL_SCOPE_ALLOWED_TYPES = exports.GOAL_SCOPE_ACTIONABLE_TYPES = exports
 exports.goalScopeRefs = goalScopeRefs;
 exports.collectGoalScope = collectGoalScope;
 const qid_1 = require("../util/qid");
-exports.GOAL_SCOPE_CONTAINER_TYPES = new Set(["epic", "feat"]);
+exports.GOAL_SCOPE_CONTAINER_TYPES = new Set(["loop", "epic", "feat"]);
 exports.GOAL_SCOPE_ACTIONABLE_TYPES = new Set(["feat", "task", "bug", "test", "spike"]);
 exports.GOAL_SCOPE_ALLOWED_TYPES = new Set([
     ...exports.GOAL_SCOPE_CONTAINER_TYPES,
@@ -75,6 +75,9 @@ function collectGoalScope(index, goal, options = {}) {
         if (queued.has(qid)) {
             return;
         }
+        if (options.maxNodes !== undefined && queued.size >= options.maxNodes) {
+            throw new Error(`goal scope traversal exceeds node limit: ${options.maxNodes}`);
+        }
         queued.add(qid);
         queue.push(qid);
     }

package/dist/graph/index_cache.js

@@ -7,21 +7,47 @@ exports.writeIndex = writeIndex;
 exports.loadIndex = loadIndex;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const filesystem_authority_1 = require("../core/filesystem_authority");
 const sort_1 = require("../util/sort");
 const atomic_1 = require("../util/atomic");
 const indexer_1 = require("./indexer");
 const staleness_1 = require("./staleness");
 const subgraphs_1 = require("./subgraphs");
-function readIndex(indexPath) {
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readIndex(root, indexPath) {
     try {
-        const raw = fs_1.default.readFileSync(indexPath, "utf8");
-        return JSON.parse(raw);
+        const relativePath = path_1.default.relative(root, indexPath).split(path_1.default.sep).join("/");
+        const parsed = JSON.parse((0, filesystem_authority_1.readContainedFile)({ root, relativePath }, "utf8"));
+        if (!isRecord(parsed) || !isRecord(parsed.meta) || !isRecord(parsed.workspaces) || !isRecord(parsed.nodes) || !isRecord(parsed.reverse_edges)) {
+            throw new Error("index cache has an invalid shape");
+        }
+        return parsed;
     }
     catch (err) {
         const message = err instanceof Error ? err.message : "unknown error";
         throw new Error(`failed to read index: ${message}`);
     }
 }
+function validateCachedNodePaths(root, config, cached) {
+    for (const node of Object.values(cached.nodes)) {
+        if (node.qid !== `${node.ws}:${node.id}` || node.source?.imported)
+            throw new Error(`invalid cached node identity: ${node.qid}`);
+        const workspace = config.workspaces[node.ws];
+        if (!workspace?.enabled)
+            throw new Error(`invalid cached node workspace: ${node.ws}`);
+        const normalized = node.path.split(path_1.default.sep).join("/");
+        const workspaceRoot = path_1.default.resolve(root, workspace.path, workspace.mdkg_dir);
+        const absolutePath = path_1.default.resolve(root, normalized);
+        const relativeWorkspacePath = path_1.default.relative(workspaceRoot, absolutePath);
+        if (path_1.default.isAbsolute(normalized) || relativeWorkspacePath.startsWith("..") || path_1.default.isAbsolute(relativeWorkspacePath)) {
+            throw new Error(`cached node path escapes workspace root: ${node.qid}`);
+        }
+        (0, filesystem_authority_1.withContainedPathSink)({ root, relativePath: normalized, operation: "read" }, () => undefined);
+    }
+    return cached;
+}
 function writeIndex(indexPath, index) {
     const sortedIndex = { ...index, nodes: (0, sort_1.sortIndexNodes)(index.nodes) };
     (0, atomic_1.atomicWriteFile)(indexPath, JSON.stringify(sortedIndex, null, 2));
@@ -31,13 +57,14 @@ function loadIndex(options) {
     const allowReindex = options.allowReindex ?? options.config.index.auto_reindex;
     const tolerant = options.tolerant ?? options.config.index.tolerant;
     const includeImports = options.includeImports ?? true;
+    const persistReindex = options.persistReindex ?? true;
     const indexPath = path_1.default.resolve(options.root, options.config.index.global_index_path);
     const withSubgraphs = (index, rebuilt, stale) => {
         if (!includeImports || Object.keys(options.config.subgraphs).length === 0) {
             return { index, rebuilt, stale, warnings: [] };
         }
         const subgraphs = (0, subgraphs_1.buildSubgraphsIndex)(options.root, options.config);
-        if (allowReindex) {
+        if (allowReindex && persistReindex) {
             (0, subgraphs_1.writeSubgraphsIndex)((0, subgraphs_1.resolveSubgraphsIndexPath)(options.root), subgraphs.index);
         }
         return {
@@ -53,15 +80,18 @@ function loadIndex(options) {
     }
     const stale = (0, staleness_1.isIndexStale)(options.root, options.config);
     if (fs_1.default.existsSync(indexPath) && !stale) {
-        return withSubgraphs(readIndex(indexPath), false, false);
+        return withSubgraphs(validateCachedNodePaths(options.root, options.config, readIndex(options.root, indexPath)), false, false);
     }
     if (allowReindex) {
         const index = (0, indexer_1.buildIndex)(options.root, options.config, { tolerant });
-        writeIndex(indexPath, index);
+        if (persistReindex) {
+            writeIndex(indexPath, index);
+        }
         return withSubgraphs(index, true, stale);
     }
     if (fs_1.default.existsSync(indexPath)) {
-        return withSubgraphs(readIndex(indexPath), false, true);
+        const cached = validateCachedNodePaths(options.root, options.config, readIndex(options.root, indexPath));
+        return withSubgraphs(cached, false, true);
     }
     throw new Error("index missing and auto-reindex is disabled");
 }

package/dist/graph/loop_bindings.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLoopIdentity = isLoopIdentity;
+exports.parseLoopRefBinding = parseLoopRefBinding;
+exports.parseLoopRefBindings = parseLoopRefBindings;
+exports.groupLoopRefBindings = groupLoopRefBindings;
+const LOOP_IDENTITY_RE = /^[a-z0-9][a-z0-9._-]*$/;
+function isLoopIdentity(value) {
+    return LOOP_IDENTITY_RE.test(value);
+}
+function parseLoopRefBinding(value) {
+    const separator = value.indexOf("=");
+    if (separator <= 0 || separator === value.length - 1) {
+        return undefined;
+    }
+    const identity = value.slice(0, separator).trim().toLowerCase();
+    const ref = value.slice(separator + 1).trim();
+    if (!isLoopIdentity(identity) || !ref) {
+        return undefined;
+    }
+    return { identity, ref };
+}
+function parseLoopRefBindings(values) {
+    return values.flatMap((value) => {
+        const binding = parseLoopRefBinding(value);
+        return binding ? [binding] : [];
+    });
+}
+function groupLoopRefBindings(bindings) {
+    const grouped = new Map();
+    for (const binding of bindings) {
+        const refs = grouped.get(binding.identity) ?? [];
+        if (!refs.includes(binding.ref)) {
+            refs.push(binding.ref);
+        }
+        grouped.set(binding.identity, refs);
+    }
+    return grouped;
+}

package/dist/graph/node.js

@@ -8,9 +8,10 @@ const agent_file_types_1 = require("./agent_file_types");
 const archive_file_1 = require("./archive_file");
 const id_1 = require("../util/id");
 const refs_1 = require("../util/refs");
+const loop_bindings_1 = require("./loop_bindings");
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const DEC_ID_RE = /^dec-[0-9]+$/;
-exports.WORK_TYPES = new Set(["goal", "epic", "feat", "task", "bug", "spike", "checkpoint", "test"]);
+exports.WORK_TYPES = new Set(["goal", "loop", "epic", "feat", "task", "bug", "spike", "checkpoint", "test"]);
 exports.DEC_TYPES = new Set(["dec"]);
 exports.ALLOWED_TYPES = new Set([
     "rule",
@@ -19,6 +20,7 @@ exports.ALLOWED_TYPES = new Set([
     "dec",
     "prop",
     "goal",
+    "loop",
     "epic",
     "feat",
     "task",
@@ -43,6 +45,45 @@ const GOAL_ATTRIBUTE_KEYS = [
     "max_iterations",
     "blocked_after_attempts",
 ];
+const LOOP_MODES = new Set([
+    "readonly",
+    "planning",
+    "patch_proposal",
+    "write_with_approval",
+    "autonomous_local",
+]);
+const LOOP_ROLES = new Set(["template", "scoped", "run_bearing"]);
+const LOOP_MATERIALIZATION_MODES = new Set(["default_children", "planning_only", "manual"]);
+const LOOP_BLOCKER_POLICIES = new Set(["spike_proposal_recommendation_continue"]);
+const LOOP_ATTRIBUTE_KEYS = [
+    "loop_mode",
+    "loop_role",
+    "scope_refs",
+    "scope_description",
+    "template_refs",
+    "materialization_mode",
+    "child_refs",
+    "pre_run_questions",
+    "question_answer_refs",
+    "pre_approved_actions",
+    "approval_gated_actions",
+    "required_actions",
+    "requested_actions",
+    "prohibited_actions",
+    "action_approval_refs",
+    "evidence_lanes",
+    "evidence_lane_refs",
+    "lane_waiver_refs",
+    "lane_waiver_decision_refs",
+    "lane_waiver_approval_refs",
+    "run_refs",
+    "decision_refs",
+    "output_refs",
+    "approval_refs",
+    "evaluation_refs",
+    "definition_of_done",
+    "blocker_policy",
+];
 function formatError(filePath, message) {
     return new Error(`${filePath}: ${message}`);
 }
@@ -215,6 +256,158 @@ function validateGoalFrontmatter(type, frontmatter, filePath) {
         parsePositiveIntegerString(blockedAfterAttempts, "blocked_after_attempts", filePath);
     }
 }
+function validateLoopRefList(frontmatter, key, filePath) {
+    const values = optionalList(frontmatter, key, filePath);
+    for (const [index, value] of values.entries()) {
+        if (typeof value !== "string" || value.trim().length === 0) {
+            throw formatError(filePath, `${key}[${index}] must not be empty`);
+        }
+        const normalized = value.includes("://") ? value : requireLowercase(value, `${key}[${index}]`, filePath);
+        if (!(0, refs_1.validatePortableOrUriRef)(normalized)) {
+            throw formatError(filePath, `${key}[${index}] must be a portable id, qid, or URI ref`);
+        }
+    }
+}
+function validateLoopStringList(frontmatter, key, filePath) {
+    const values = optionalList(frontmatter, key, filePath);
+    const seen = new Set();
+    for (const [index, value] of values.entries()) {
+        if (typeof value !== "string" || value.trim().length === 0) {
+            throw formatError(filePath, `${key}[${index}] must not be empty`);
+        }
+        const normalized = value.trim().toLowerCase();
+        if (!(0, loop_bindings_1.isLoopIdentity)(normalized)) {
+            throw formatError(filePath, `${key}[${index}] must be a stable lowercase identity`);
+        }
+        if (value.trim() !== normalized) {
+            throw formatError(filePath, `${key}[${index}] must be lowercase; use ${normalized}`);
+        }
+        if (seen.has(normalized)) {
+            throw formatError(filePath, `${key}[${index}] duplicates identity ${normalized}`);
+        }
+        seen.add(normalized);
+    }
+}
+function validateLoopBindingList(frontmatter, key, identityKey, refKeys, filePath, requireEveryRefKey = false) {
+    const values = optionalList(frontmatter, key, filePath);
+    const identities = new Set(optionalList(frontmatter, identityKey, filePath).map((value) => value.toLowerCase()));
+    const refsByKey = refKeys.map((refKey) => new Set(optionalList(frontmatter, refKey, filePath)));
+    const seen = new Set();
+    for (const [index, value] of values.entries()) {
+        if (typeof value !== "string") {
+            throw formatError(filePath, `${key}[${index}] must use <identity>=<ref>`);
+        }
+        const binding = (0, loop_bindings_1.parseLoopRefBinding)(value);
+        if (!binding) {
+            throw formatError(filePath, `${key}[${index}] must use <identity>=<ref>`);
+        }
+        if (!identities.has(binding.identity)) {
+            throw formatError(filePath, `${key}[${index}] references undeclared ${identityKey} identity ${binding.identity}`);
+        }
+        const normalizedRef = binding.ref.includes("://")
+            ? binding.ref
+            : requireLowercase(binding.ref, `${key}[${index}]`, filePath);
+        if (!(0, refs_1.validatePortableOrUriRef)(normalizedRef)) {
+            throw formatError(filePath, `${key}[${index}] must reference a portable id, qid, or URI ref`);
+        }
+        const included = requireEveryRefKey
+            ? refsByKey.every((refs) => refs.has(binding.ref))
+            : refsByKey.some((refs) => refs.has(binding.ref));
+        if (!included) {
+            const operator = requireEveryRefKey ? "each of" : "one of";
+            throw formatError(filePath, `${key}[${index}] ref ${binding.ref} must also appear in ${operator} ${refKeys.join(", ")}`);
+        }
+        const pair = `${binding.identity}\u0000${binding.ref}`;
+        if (seen.has(pair)) {
+            throw formatError(filePath, `${key}[${index}] duplicates ${binding.identity}=${binding.ref}`);
+        }
+        seen.add(pair);
+    }
+}
+function validateLoopActionSets(frontmatter, filePath) {
+    const normalized = (key) => optionalList(frontmatter, key, filePath).map((value) => value.trim().toLowerCase());
+    const preApproved = new Set(normalized("pre_approved_actions"));
+    const approvalGated = new Set(normalized("approval_gated_actions"));
+    const required = normalized("required_actions");
+    const requested = normalized("requested_actions");
+    const prohibited = new Set(normalized("prohibited_actions"));
+    for (const action of preApproved) {
+        if (approvalGated.has(action)) {
+            throw formatError(filePath, `action ${action} cannot be both pre_approved_actions and approval_gated_actions`);
+        }
+        if (prohibited.has(action)) {
+            throw formatError(filePath, `action ${action} cannot be both pre_approved_actions and prohibited_actions`);
+        }
+    }
+    for (const action of approvalGated) {
+        if (prohibited.has(action)) {
+            throw formatError(filePath, `action ${action} cannot be both approval_gated_actions and prohibited_actions`);
+        }
+    }
+    for (const [key, actions] of [["required_actions", required], ["requested_actions", requested]]) {
+        for (const action of actions) {
+            if (!preApproved.has(action) && !approvalGated.has(action)) {
+                throw formatError(filePath, `${key} references undeclared action ${action}`);
+            }
+            if (prohibited.has(action)) {
+                throw formatError(filePath, `${key} cannot include prohibited action ${action}`);
+            }
+        }
+    }
+}
+function validateLoopFrontmatter(type, frontmatter, filePath) {
+    if (type !== "loop") {
+        return;
+    }
+    const loopMode = requireLowercase(expectString(frontmatter, "loop_mode", filePath), "loop_mode", filePath);
+    if (!LOOP_MODES.has(loopMode)) {
+        throw formatError(filePath, `loop_mode must be one of ${Array.from(LOOP_MODES).join(", ")}`);
+    }
+    const loopRole = requireLowercase(expectString(frontmatter, "loop_role", filePath), "loop_role", filePath);
+    if (!LOOP_ROLES.has(loopRole)) {
+        throw formatError(filePath, `loop_role must be one of ${Array.from(LOOP_ROLES).join(", ")}`);
+    }
+    const materializationMode = requireLowercase(expectString(frontmatter, "materialization_mode", filePath), "materialization_mode", filePath);
+    if (!LOOP_MATERIALIZATION_MODES.has(materializationMode)) {
+        throw formatError(filePath, `materialization_mode must be one of ${Array.from(LOOP_MATERIALIZATION_MODES).join(", ")}`);
+    }
+    const blockerPolicy = requireLowercase(expectString(frontmatter, "blocker_policy", filePath), "blocker_policy", filePath);
+    if (!LOOP_BLOCKER_POLICIES.has(blockerPolicy)) {
+        throw formatError(filePath, `blocker_policy must be one of ${Array.from(LOOP_BLOCKER_POLICIES).join(", ")}`);
+    }
+    expectString(frontmatter, "definition_of_done", filePath);
+    optionalString(frontmatter, "scope_description", filePath);
+    for (const key of [
+        "pre_run_questions",
+        "pre_approved_actions",
+        "approval_gated_actions",
+        "required_actions",
+        "requested_actions",
+        "prohibited_actions",
+        "evidence_lanes",
+    ]) {
+        validateLoopStringList(frontmatter, key, filePath);
+    }
+    validateLoopActionSets(frontmatter, filePath);
+    for (const key of [
+        "scope_refs",
+        "template_refs",
+        "child_refs",
+        "lane_waiver_refs",
+        "run_refs",
+        "decision_refs",
+        "output_refs",
+        "approval_refs",
+        "evaluation_refs",
+    ]) {
+        validateLoopRefList(frontmatter, key, filePath);
+    }
+    validateLoopBindingList(frontmatter, "question_answer_refs", "pre_run_questions", ["decision_refs"], filePath);
+    validateLoopBindingList(frontmatter, "action_approval_refs", "approval_gated_actions", ["approval_refs"], filePath);
+    validateLoopBindingList(frontmatter, "evidence_lane_refs", "evidence_lanes", ["run_refs", "output_refs", "evaluation_refs", "evidence_refs"], filePath);
+    validateLoopBindingList(frontmatter, "lane_waiver_decision_refs", "evidence_lanes", ["lane_waiver_refs", "decision_refs"], filePath, true);
+    validateLoopBindingList(frontmatter, "lane_waiver_approval_refs", "evidence_lanes", ["approval_refs"], filePath);
+}
 function extractGoalAttributes(type, frontmatter) {
     if (type !== "goal") {
         return {};
@@ -228,6 +421,19 @@ function extractGoalAttributes(type, frontmatter) {
     }
     return attributes;
 }
+function extractLoopAttributes(type, frontmatter) {
+    if (type !== "loop") {
+        return {};
+    }
+    const attributes = {};
+    for (const key of LOOP_ATTRIBUTE_KEYS) {
+        const value = frontmatter[key];
+        if (value !== undefined) {
+            attributes[key] = value;
+        }
+    }
+    return attributes;
+}
 function requireTemplateSchema(type, templateSchemas, filePath) {
     const schema = templateSchemas[type];
     if (!schema) {
@@ -306,6 +512,7 @@ function parseNode(content, filePath, options) {
     (0, agent_file_types_1.validateAgentFrontmatter)(type, frontmatter, filePath);
     (0, archive_file_1.validateArchiveFrontmatter)(type, frontmatter, filePath);
     validateGoalFrontmatter(type, frontmatter, filePath);
+    validateLoopFrontmatter(type, frontmatter, filePath);
     const idValue = requireLowercase(expectString(frontmatter, "id", filePath), "id", filePath);
     const id = isPortableType
         ? requirePortableIdFormat(idValue, "id", filePath)
@@ -376,6 +583,7 @@ function parseNode(content, filePath, options) {
     });
     const attributes = {
         ...extractGoalAttributes(type, frontmatter),
+        ...extractLoopAttributes(type, frontmatter),
         ...(0, agent_file_types_1.extractAgentAttributes)(type, frontmatter),
         ...(0, archive_file_1.extractArchiveAttributes)(type, frontmatter),
     };