@joshski/dust 0.1.97 → 0.1.98

package/dist/patch.js

@@ -0,0 +1,1632 @@
+// lib/validation/index.ts
+import { relative } from "node:path";
+
+// lib/validation/overlay-filesystem.ts
+function createOverlayFileSystem(base, patchFiles, deletedPaths = new Set) {
+  const patchDirs = new Set;
+  for (const path of patchFiles.keys()) {
+    let dir = path;
+    while (dir.includes("/")) {
+      dir = dir.substring(0, dir.lastIndexOf("/"));
+      if (dir)
+        patchDirs.add(dir);
+    }
+  }
+  function isDeleted(path) {
+    return deletedPaths.has(path);
+  }
+  return {
+    exists(path) {
+      if (isDeleted(path))
+        return false;
+      return patchFiles.has(path) || patchDirs.has(path) || base.exists(path);
+    },
+    async readFile(path) {
+      if (isDeleted(path)) {
+        const error = new Error(`ENOENT: no such file or directory, open '${path}'`);
+        error.code = "ENOENT";
+        throw error;
+      }
+      const patchContent = patchFiles.get(path);
+      if (patchContent !== undefined) {
+        return patchContent;
+      }
+      return base.readFile(path);
+    },
+    async readdir(path) {
+      const prefix = `${path}/`;
+      const entries = new Set;
+      for (const patchPath of patchFiles.keys()) {
+        if (patchPath.startsWith(prefix)) {
+          const relative = patchPath.slice(prefix.length);
+          const firstSegment = relative.split("/")[0];
+          entries.add(firstSegment);
+        }
+      }
+      try {
+        const baseEntries = await base.readdir(path);
+        for (const entry of baseEntries) {
+          const entryPath = `${path}/${entry}`;
+          if (!isDeleted(entryPath)) {
+            entries.add(entry);
+          }
+        }
+      } catch (error) {
+        if (error.code !== "ENOENT") {
+          throw error;
+        }
+      }
+      return Array.from(entries);
+    },
+    isDirectory(path) {
+      if (isDeleted(path))
+        return false;
+      return patchDirs.has(path) || base.isDirectory(path);
+    }
+  };
+}
+
+// lib/artifacts/parsed-artifact.ts
+var MARKDOWN_LINK_PATTERN = /\[([^\]]+)\]\(([^)]+)\)/g;
+function parseArtifact(filePath, content) {
+  const lines = content.split(`
+`);
+  let title = null;
+  let titleLine = null;
+  let openingSentence = null;
+  let openingSentenceLine = null;
+  const sections = [];
+  const allLinks = [];
+  let currentSection = null;
+  let inCodeFence = false;
+  let openingSentenceResolved = false;
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i];
+    const lineNumber = i + 1;
+    if (line.startsWith("```")) {
+      inCodeFence = !inCodeFence;
+      continue;
+    }
+    if (inCodeFence) {
+      continue;
+    }
+    const h1Match = line.match(/^#\s+(.+)$/);
+    if (h1Match) {
+      if (title === null) {
+        title = h1Match[1].trim();
+        titleLine = lineNumber;
+      } else {
+        if (currentSection !== null) {
+          currentSection.endLine = findLastNonEmptyLine(lines, currentSection.startLine, lineNumber - 2);
+          sections.push(currentSection);
+          currentSection = null;
+        }
+      }
+      continue;
+    }
+    const headingMatch = line.match(/^(#{2,6})\s+(.+)$/);
+    if (headingMatch) {
+      openingSentenceResolved = true;
+      if (currentSection !== null) {
+        currentSection.endLine = findLastNonEmptyLine(lines, currentSection.startLine, lineNumber - 2);
+        sections.push(currentSection);
+      }
+      currentSection = {
+        heading: headingMatch[2].trim(),
+        level: headingMatch[1].length,
+        startLine: lineNumber,
+        endLine: -1,
+        links: []
+      };
+      continue;
+    }
+    if (shouldCheckForOpeningSentence(title, openingSentenceResolved, line)) {
+      const result = tryExtractOpeningSentence(lines, i);
+      openingSentence = result.sentence;
+      openingSentenceLine = result.sentence !== null ? lineNumber : null;
+      openingSentenceResolved = true;
+    }
+    const linkMatches = line.matchAll(MARKDOWN_LINK_PATTERN);
+    for (const match of linkMatches) {
+      const link = {
+        text: match[1],
+        target: match[2],
+        line: lineNumber
+      };
+      allLinks.push(link);
+      if (currentSection !== null) {
+        currentSection.links.push(link);
+      }
+    }
+  }
+  if (currentSection !== null) {
+    currentSection.endLine = findLastNonEmptyLine(lines, currentSection.startLine, lines.length - 1);
+    sections.push(currentSection);
+  }
+  return {
+    filePath,
+    rawContent: content,
+    title,
+    titleLine,
+    openingSentence,
+    openingSentenceLine,
+    sections,
+    allLinks
+  };
+}
+function shouldCheckForOpeningSentence(title, resolved, line) {
+  if (title === null || resolved) {
+    return false;
+  }
+  const trimmed = line.trim();
+  return trimmed !== "" && !isStructuralElement(trimmed);
+}
+function tryExtractOpeningSentence(lines, startIndex) {
+  const paragraph = collectParagraph(lines, startIndex);
+  return { sentence: extractFirstSentence(paragraph) };
+}
+function findLastNonEmptyLine(lines, contentStartIndex, fromIndex) {
+  for (let i = fromIndex;i >= contentStartIndex; i--) {
+    if (lines[i].trim() !== "") {
+      return i + 1;
+    }
+  }
+  return contentStartIndex;
+}
+var LIST_ITEM_PREFIXES = ["-", "*", "+"];
+var STRUCTURAL_PREFIXES = ["#", "```", ">"];
+function isStructuralElement(line) {
+  if (STRUCTURAL_PREFIXES.some((prefix) => line.startsWith(prefix))) {
+    return true;
+  }
+  if (LIST_ITEM_PREFIXES.some((prefix) => line.startsWith(prefix))) {
+    return true;
+  }
+  return /^\d+\./.test(line);
+}
+function isBlockBreak(line) {
+  return STRUCTURAL_PREFIXES.some((prefix) => line.startsWith(prefix));
+}
+function collectParagraph(lines, startIndex) {
+  const parts = [];
+  for (let i = startIndex;i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line === "" || isBlockBreak(line)) {
+      break;
+    }
+    parts.push(line);
+  }
+  return parts.join(" ");
+}
+function extractFirstSentence(paragraph) {
+  const match = paragraph.match(/^(.+?[.?!])(?:\s|$)/);
+  return match ? match[1] : null;
+}
+
+// lib/lint/validators/content-validator.ts
+var REQUIRED_TASK_HEADINGS = ["Blocked By", "Definition of Done"];
+var MAX_OPENING_SENTENCE_LENGTH = 150;
+var NON_IMPERATIVE_STARTERS = new Set([
+  "the",
+  "a",
+  "an",
+  "this",
+  "that",
+  "these",
+  "those",
+  "we",
+  "it",
+  "they",
+  "you",
+  "i"
+]);
+function validateOpeningSentence(artifact) {
+  if (!artifact.openingSentence) {
+    return {
+      file: artifact.filePath,
+      line: artifact.titleLine ?? undefined,
+      message: "Missing or malformed opening sentence after H1 heading"
+    };
+  }
+  return null;
+}
+function validateOpeningSentenceLength(artifact) {
+  const openingSentence = artifact.openingSentence;
+  if (!openingSentence) {
+    return null;
+  }
+  if (openingSentence.length > MAX_OPENING_SENTENCE_LENGTH) {
+    return {
+      file: artifact.filePath,
+      line: artifact.openingSentenceLine ?? undefined,
+      message: `Opening sentence is ${openingSentence.length} characters (max ${MAX_OPENING_SENTENCE_LENGTH}). Split into multiple sentences; only the first sentence is checked.`
+    };
+  }
+  return null;
+}
+function validateImperativeOpeningSentence(artifact) {
+  const openingSentence = artifact.openingSentence;
+  if (!openingSentence) {
+    return null;
+  }
+  const firstWord = openingSentence.split(/\s/)[0].replace(/[^a-zA-Z]/g, "");
+  const lower = firstWord.toLowerCase();
+  if (NON_IMPERATIVE_STARTERS.has(lower) || lower.endsWith("ing")) {
+    const preview = openingSentence.length > 40 ? `${openingSentence.slice(0, 40)}...` : openingSentence;
+    return {
+      file: artifact.filePath,
+      line: artifact.openingSentenceLine ?? undefined,
+      message: `Opening sentence should use imperative form (e.g., "Add X" not "This adds X"). Found: "${preview}"`
+    };
+  }
+  return null;
+}
+function validateTaskHeadings(artifact) {
+  const violations = [];
+  const sectionHeadings = new Set(artifact.sections.map((s) => s.heading));
+  for (const heading of REQUIRED_TASK_HEADINGS) {
+    if (!sectionHeadings.has(heading)) {
+      violations.push({
+        file: artifact.filePath,
+        message: `Missing required heading: "## ${heading}"`
+      });
+    }
+  }
+  return violations;
+}
+
+// lib/lint/validators/directory-validator.ts
+async function validateContentDirectoryFiles(dirPath, fileSystem) {
+  const violations = [];
+  let entries;
+  try {
+    entries = await fileSystem.readdir(dirPath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  for (const entry of entries) {
+    const entryPath = `${dirPath}/${entry}`;
+    if (entry.startsWith(".")) {
+      violations.push({
+        file: entryPath,
+        message: `Hidden file "${entry}" found in content directory`
+      });
+      continue;
+    }
+    if (fileSystem.isDirectory(entryPath)) {
+      violations.push({
+        file: entryPath,
+        message: `Subdirectory "${entry}" found in content directory (content directories should be flat)`
+      });
+      continue;
+    }
+    if (!entry.endsWith(".md")) {
+      violations.push({
+        file: entryPath,
+        message: `Non-markdown file "${entry}" found in content directory`
+      });
+    }
+  }
+  return violations;
+}
+
+// lib/markdown/markdown-utilities.ts
+var MARKDOWN_LINK_PATTERN2 = /\[([^\]]+)\]\(([^)]+)\)/;
+
+// lib/artifacts/workflow-tasks.ts
+var IDEA_TRANSITION_PREFIXES = [
+  "Refine Idea: ",
+  "Decompose Idea: ",
+  "Shelve Idea: ",
+  "Expedite Idea: "
+];
+function titleToFilename(title) {
+  return `${title.toLowerCase().replace(/\./g, "-").replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "")}.md`;
+}
+
+// lib/lint/validators/filename-validator.ts
+var SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*\.md$/;
+function validateFilename(filePath) {
+  const parts = filePath.split("/");
+  const filename = parts[parts.length - 1];
+  if (!SLUG_PATTERN.test(filename)) {
+    return {
+      file: filePath,
+      message: `Filename "${filename}" does not match slug-style naming`
+    };
+  }
+  return null;
+}
+function validateTitleFilenameMatch(artifact) {
+  const title = artifact.title;
+  if (!title) {
+    return null;
+  }
+  const parts = artifact.filePath.split("/");
+  const actualFilename = parts[parts.length - 1];
+  const expectedFilename = titleToFilename(title);
+  if (actualFilename !== expectedFilename) {
+    return {
+      file: artifact.filePath,
+      message: `Filename "${actualFilename}" does not match title "${title}" (expected "${expectedFilename}")`
+    };
+  }
+  return null;
+}
+
+// lib/lint/validators/idea-validator.ts
+var WORKFLOW_PREFIX_TO_SECTION = {
+  "Refine Idea: ": "Refines Idea",
+  "Decompose Idea: ": "Decomposes Idea",
+  "Shelve Idea: ": "Shelves Idea",
+  "Expedite Idea: ": "Expedites Idea"
+};
+function validateH2Heading(filePath, line, lineNumber, inOpenQuestions, currentQuestionLine) {
+  const violations = [];
+  if (inOpenQuestions && currentQuestionLine !== null) {
+    violations.push({
+      file: filePath,
+      message: "Question has no options listed beneath it",
+      line: currentQuestionLine
+    });
+  }
+  if (inOpenQuestions && line !== "## Open Questions") {
+    violations.push({
+      file: filePath,
+      message: "Open Questions must be the last section in an idea file. Move this section above ## Open Questions.",
+      line: lineNumber
+    });
+  }
+  const headingText = line.slice(3).trimEnd();
+  if (headingText.toLowerCase() === "open questions" && headingText !== "Open Questions") {
+    violations.push({
+      file: filePath,
+      message: `Heading "${line.trimEnd()}" should be "## Open Questions"`,
+      line: lineNumber
+    });
+  }
+  return violations;
+}
+function validateIdeaOpenQuestions(artifact) {
+  const violations = [];
+  const lines = artifact.rawContent.split(`
+`);
+  const filePath = artifact.filePath;
+  const topLevelStructureMessage = "Open Questions must use `### Question?` headings and `#### Option` headings at the top level. Put supporting markdown (including lists and code blocks) under an option heading. Run `dust new idea` to see the expected format.";
+  let inOpenQuestions = false;
+  let currentQuestionLine = null;
+  let inOption = false;
+  let inCodeBlock = false;
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i];
+    const trimmedLine = line.trimEnd();
+    const nonWhitespaceLine = line.trim();
+    if (inOpenQuestions && line.startsWith("```")) {
+      if (!inOption && !inCodeBlock) {
+        violations.push({
+          file: filePath,
+          message: topLevelStructureMessage,
+          line: i + 1
+        });
+      }
+      inCodeBlock = !inCodeBlock;
+      continue;
+    }
+    if (inCodeBlock)
+      continue;
+    if (line.startsWith("## ")) {
+      violations.push(...validateH2Heading(filePath, line, i + 1, inOpenQuestions, currentQuestionLine));
+      inOpenQuestions = line === "## Open Questions";
+      currentQuestionLine = null;
+      inOption = false;
+      inCodeBlock = false;
+      continue;
+    }
+    if (!inOpenQuestions)
+      continue;
+    if (line.startsWith("### ")) {
+      inOption = false;
+      if (currentQuestionLine !== null) {
+        violations.push({
+          file: filePath,
+          message: "Question has no options listed beneath it",
+          line: currentQuestionLine
+        });
+      }
+      if (!trimmedLine.endsWith("?")) {
+        violations.push({
+          file: filePath,
+          message: 'Questions must end with "?" (e.g., "### Should we take our own payments?")',
+          line: i + 1
+        });
+        currentQuestionLine = null;
+      } else {
+        currentQuestionLine = i + 1;
+      }
+      continue;
+    }
+    if (line.startsWith("#### ")) {
+      currentQuestionLine = null;
+      inOption = true;
+      continue;
+    }
+    if (nonWhitespaceLine && !inOption) {
+      violations.push({
+        file: filePath,
+        message: topLevelStructureMessage,
+        line: i + 1
+      });
+    }
+  }
+  if (inOpenQuestions && currentQuestionLine !== null) {
+    violations.push({
+      file: filePath,
+      message: "Question has no options listed beneath it",
+      line: currentQuestionLine
+    });
+  }
+  return violations;
+}
+function validateIdeaTransitionTitle(artifact, ideasPath, fileSystem) {
+  const title = artifact.title;
+  if (!title) {
+    return null;
+  }
+  for (const prefix of IDEA_TRANSITION_PREFIXES) {
+    if (title.startsWith(prefix)) {
+      const ideaTitle = title.slice(prefix.length);
+      const ideaFilename = titleToFilename(ideaTitle);
+      if (!fileSystem.exists(`${ideasPath}/${ideaFilename}`)) {
+        return {
+          file: artifact.filePath,
+          message: `Idea transition task references non-existent idea: "${ideaTitle}" (expected file "${ideaFilename}" in ideas/)`
+        };
+      }
+      return null;
+    }
+  }
+  return null;
+}
+function validateWorkflowTaskBodySection(artifact, ideasPath, fileSystem) {
+  const violations = [];
+  const title = artifact.title;
+  if (!title)
+    return violations;
+  let matchedPrefix = null;
+  for (const prefix of IDEA_TRANSITION_PREFIXES) {
+    if (title.startsWith(prefix)) {
+      matchedPrefix = prefix;
+      break;
+    }
+  }
+  if (!matchedPrefix)
+    return violations;
+  const expectedHeading = WORKFLOW_PREFIX_TO_SECTION[matchedPrefix];
+  const section = artifact.sections.find((s) => s.heading === expectedHeading && s.level === 2);
+  if (!section) {
+    violations.push({
+      file: artifact.filePath,
+      message: `Workflow task with "${matchedPrefix.trim()}" prefix is missing required "## ${expectedHeading}" section. Add a section with a link to the idea file, e.g.:
+
+## ${expectedHeading}
+
+- [Idea Title](../ideas/idea-slug.md)`
+    });
+    return violations;
+  }
+  if (section.links.length === 0) {
+    violations.push({
+      file: artifact.filePath,
+      message: `"## ${expectedHeading}" section contains no link. Add a markdown link to the idea file, e.g.:
+
+- [Idea Title](../ideas/idea-slug.md)`,
+      line: section.startLine
+    });
+    return violations;
+  }
+  const ideaLinks = section.links.filter((l) => l.target.includes("/ideas/") || l.target.startsWith("../ideas/"));
+  if (ideaLinks.length === 0) {
+    violations.push({
+      file: artifact.filePath,
+      message: `"## ${expectedHeading}" section contains no link to an idea file. Links must point to a file in ../ideas/, e.g.:
+
+- [Idea Title](../ideas/idea-slug.md)`,
+      line: section.startLine
+    });
+    return violations;
+  }
+  for (const link of ideaLinks) {
+    const slugMatch = link.target.match(/([^/]+)\.md$/);
+    if (!slugMatch)
+      continue;
+    const ideaSlug = slugMatch[1];
+    const ideaFilePath = `${ideasPath}/${ideaSlug}.md`;
+    if (!fileSystem.exists(ideaFilePath)) {
+      violations.push({
+        file: artifact.filePath,
+        message: `Link to idea "${link.text}" points to non-existent file: ${ideaSlug}.md. Either create the idea file at ideas/${ideaSlug}.md or update the link to point to an existing idea.`,
+        line: link.line
+      });
+    }
+  }
+  return violations;
+}
+
+// lib/lint/validators/link-validator.ts
+import { dirname, resolve } from "node:path";
+var SEMANTIC_RULES = [
+  {
+    sectionHeading: "Principles",
+    requiredPath: "/.dust/principles/",
+    description: "principle"
+  },
+  {
+    sectionHeading: "Blocked By",
+    requiredPath: "/.dust/tasks/",
+    description: "task"
+  }
+];
+function isExternalOrAnchorLink(target) {
+  return target.startsWith("http://") || target.startsWith("https://") || target.startsWith("#");
+}
+function isAnchorLink(target) {
+  return target.startsWith("#");
+}
+function isExternalLink(target) {
+  return target.startsWith("http://") || target.startsWith("https://");
+}
+function validateLinks(artifact, fileSystem) {
+  const violations = [];
+  const fileDir = dirname(artifact.filePath);
+  for (const link of artifact.allLinks) {
+    if (isExternalOrAnchorLink(link.target)) {
+      continue;
+    }
+    if (link.target.startsWith("/")) {
+      violations.push({
+        file: artifact.filePath,
+        message: `Absolute link not allowed: "${link.target}" (use a relative path instead)`,
+        line: link.line
+      });
+      continue;
+    }
+    const targetPath = link.target.split("#")[0];
+    const resolvedPath = resolve(fileDir, targetPath);
+    if (!fileSystem.exists(resolvedPath)) {
+      violations.push({
+        file: artifact.filePath,
+        message: `Broken link: "${link.target}"`,
+        line: link.line
+      });
+    }
+  }
+  return violations;
+}
+function validateSectionLink(artifact, link, rule) {
+  const sectionLabel = `## ${rule.sectionHeading}`;
+  if (isAnchorLink(link.target)) {
+    return {
+      file: artifact.filePath,
+      message: `Link in "${sectionLabel}" must point to a ${rule.description} file, not an anchor: "${link.target}"`,
+      line: link.line
+    };
+  }
+  if (isExternalLink(link.target)) {
+    return {
+      file: artifact.filePath,
+      message: `Link in "${sectionLabel}" must point to a ${rule.description} file, not an external URL: "${link.target}"`,
+      line: link.line
+    };
+  }
+  const fileDir = dirname(artifact.filePath);
+  const targetPath = link.target.split("#")[0];
+  const resolvedPath = resolve(fileDir, targetPath);
+  if (!resolvedPath.includes(rule.requiredPath)) {
+    return {
+      file: artifact.filePath,
+      message: `Link in "${sectionLabel}" must point to a ${rule.description} file: "${link.target}"`,
+      line: link.line
+    };
+  }
+  return null;
+}
+function validateSemanticLinks(artifact) {
+  const violations = [];
+  for (const section of artifact.sections) {
+    const rule = SEMANTIC_RULES.find((r) => r.sectionHeading === section.heading);
+    if (!rule)
+      continue;
+    for (const link of section.links) {
+      const violation = validateSectionLink(artifact, link, rule);
+      if (violation) {
+        violations.push(violation);
+      }
+    }
+  }
+  return violations;
+}
+function validatePrincipleHierarchyLinks(artifact) {
+  const violations = [];
+  const hierarchySections = ["Parent Principle", "Sub-Principles"];
+  for (const section of artifact.sections) {
+    if (!hierarchySections.includes(section.heading))
+      continue;
+    const sectionLabel = `## ${section.heading}`;
+    const fileDir = dirname(artifact.filePath);
+    for (const link of section.links) {
+      if (isAnchorLink(link.target)) {
+        violations.push({
+          file: artifact.filePath,
+          message: `Link in "${sectionLabel}" must point to a principle file, not an anchor: "${link.target}"`,
+          line: link.line
+        });
+        continue;
+      }
+      if (isExternalLink(link.target)) {
+        violations.push({
+          file: artifact.filePath,
+          message: `Link in "${sectionLabel}" must point to a principle file, not an external URL: "${link.target}"`,
+          line: link.line
+        });
+        continue;
+      }
+      const targetPath = link.target.split("#")[0];
+      const resolvedPath = resolve(fileDir, targetPath);
+      if (!resolvedPath.includes("/.dust/principles/")) {
+        violations.push({
+          file: artifact.filePath,
+          message: `Link in "${sectionLabel}" must point to a principle file: "${link.target}"`,
+          line: link.line
+        });
+      }
+    }
+  }
+  return violations;
+}
+
+// lib/lint/validators/principle-hierarchy.ts
+import { dirname as dirname2, resolve as resolve2 } from "node:path";
+var REQUIRED_PRINCIPLE_HEADINGS = ["Parent Principle", "Sub-Principles"];
+function validatePrincipleHierarchySections(artifact) {
+  const violations = [];
+  const sectionHeadings = new Set(artifact.sections.map((s) => s.heading));
+  for (const heading of REQUIRED_PRINCIPLE_HEADINGS) {
+    if (!sectionHeadings.has(heading)) {
+      violations.push({
+        file: artifact.filePath,
+        message: `Missing required heading: "## ${heading}"`
+      });
+    }
+  }
+  return violations;
+}
+function isLocalPrincipleLink(target, resolvedPath) {
+  const isLocalLink = !target.startsWith("#") && !target.startsWith("http://") && !target.startsWith("https://");
+  return isLocalLink && resolvedPath.includes("/.dust/principles/");
+}
+function extractPrincipleRelationships(artifact) {
+  const fileDir = dirname2(artifact.filePath);
+  const parentPrinciples = [];
+  const subPrinciples = [];
+  for (const section of artifact.sections) {
+    if (section.heading !== "Parent Principle" && section.heading !== "Sub-Principles") {
+      continue;
+    }
+    for (const link of section.links) {
+      const targetPath = link.target.split("#")[0];
+      const resolvedPath = resolve2(fileDir, targetPath);
+      if (!isLocalPrincipleLink(link.target, resolvedPath)) {
+        continue;
+      }
+      if (section.heading === "Parent Principle") {
+        parentPrinciples.push(resolvedPath);
+      } else {
+        subPrinciples.push(resolvedPath);
+      }
+    }
+  }
+  return { filePath: artifact.filePath, parentPrinciples, subPrinciples };
+}
+function validateBidirectionalLinks(allPrincipleRelationships) {
+  const violations = [];
+  const relationshipMap = new Map;
+  for (const rel of allPrincipleRelationships) {
+    relationshipMap.set(rel.filePath, rel);
+  }
+  for (const rel of allPrincipleRelationships) {
+    for (const parentPath of rel.parentPrinciples) {
+      const parentRel = relationshipMap.get(parentPath);
+      if (parentRel && !parentRel.subPrinciples.includes(rel.filePath)) {
+        violations.push({
+          file: rel.filePath,
+          message: `Parent principle "${parentPath}" does not list this principle as a sub-principle`
+        });
+      }
+    }
+    for (const subPrinciplePath of rel.subPrinciples) {
+      const subPrincipleRel = relationshipMap.get(subPrinciplePath);
+      if (subPrincipleRel && !subPrincipleRel.parentPrinciples.includes(rel.filePath)) {
+        violations.push({
+          file: rel.filePath,
+          message: `Sub-principle "${subPrinciplePath}" does not list this principle as its parent`
+        });
+      }
+    }
+  }
+  return violations;
+}
+function validateNoCycles(allPrincipleRelationships) {
+  const violations = [];
+  const relationshipMap = new Map;
+  for (const rel of allPrincipleRelationships) {
+    relationshipMap.set(rel.filePath, rel);
+  }
+  for (const rel of allPrincipleRelationships) {
+    const visited = new Set;
+    const path = [];
+    let current = rel.filePath;
+    while (current) {
+      if (visited.has(current)) {
+        const cycleStart = path.indexOf(current);
+        const cyclePath = path.slice(cycleStart).concat(current);
+        violations.push({
+          file: rel.filePath,
+          message: `Cycle detected in principle hierarchy: ${cyclePath.join(" -> ")}`
+        });
+        break;
+      }
+      visited.add(current);
+      path.push(current);
+      const currentRel = relationshipMap.get(current);
+      if (currentRel && currentRel.parentPrinciples.length > 0) {
+        current = currentRel.parentPrinciples[0];
+      } else {
+        current = null;
+      }
+    }
+  }
+  return violations;
+}
+
+// lib/validation/validation-pipeline.ts
+var CONTENT_DIRS = ["principles", "facts", "ideas", "tasks"];
+async function parseArtifacts(fileSystem, dustPath) {
+  const artifacts = new Map;
+  const byType = {
+    ideas: [],
+    tasks: [],
+    principles: [],
+    facts: []
+  };
+  const rootFiles = [];
+  const violations = [];
+  let rootEntries;
+  try {
+    rootEntries = await fileSystem.readdir(dustPath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      rootEntries = [];
+    } else {
+      throw error;
+    }
+  }
+  for (const entry of rootEntries) {
+    if (!entry.endsWith(".md"))
+      continue;
+    const filePath = `${dustPath}/${entry}`;
+    let content;
+    try {
+      content = await fileSystem.readFile(filePath);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        continue;
+      }
+      throw error;
+    }
+    const artifact = parseArtifact(filePath, content);
+    artifacts.set(filePath, artifact);
+    rootFiles.push(artifact);
+  }
+  for (const dir of CONTENT_DIRS) {
+    const dirPath = `${dustPath}/${dir}`;
+    violations.push(...await validateContentDirectoryFiles(dirPath, fileSystem));
+    let entries;
+    try {
+      entries = await fileSystem.readdir(dirPath);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        continue;
+      }
+      throw error;
+    }
+    for (const entry of entries) {
+      if (!entry.endsWith(".md"))
+        continue;
+      const filePath = `${dirPath}/${entry}`;
+      let content;
+      try {
+        content = await fileSystem.readFile(filePath);
+      } catch (error) {
+        if (error.code === "ENOENT") {
+          continue;
+        }
+        throw error;
+      }
+      const artifact = parseArtifact(filePath, content);
+      artifacts.set(filePath, artifact);
+      byType[dir].push(artifact);
+    }
+  }
+  return {
+    context: {
+      artifacts,
+      byType,
+      rootFiles,
+      dustPath,
+      fileSystem
+    },
+    violations
+  };
+}
+function validateArtifacts(context) {
+  const violations = [];
+  const { byType, rootFiles, dustPath, fileSystem } = context;
+  const ideasPath = `${dustPath}/ideas`;
+  for (const artifact of rootFiles) {
+    violations.push(...validateLinks(artifact, fileSystem));
+  }
+  for (const artifacts of Object.values(byType)) {
+    for (const artifact of artifacts) {
+      const openingSentenceViolation = validateOpeningSentence(artifact);
+      if (openingSentenceViolation)
+        violations.push(openingSentenceViolation);
+      const lengthViolation = validateOpeningSentenceLength(artifact);
+      if (lengthViolation)
+        violations.push(lengthViolation);
+      const titleViolation = validateTitleFilenameMatch(artifact);
+      if (titleViolation)
+        violations.push(titleViolation);
+      violations.push(...validateLinks(artifact, fileSystem));
+    }
+  }
+  for (const artifact of byType.ideas) {
+    violations.push(...validateIdeaOpenQuestions(artifact));
+  }
+  for (const artifact of byType.tasks) {
+    const filenameViolation = validateFilename(artifact.filePath);
+    if (filenameViolation)
+      violations.push(filenameViolation);
+    violations.push(...validateTaskHeadings(artifact));
+    violations.push(...validateSemanticLinks(artifact));
+    const imperativeViolation = validateImperativeOpeningSentence(artifact);
+    if (imperativeViolation)
+      violations.push(imperativeViolation);
+    const ideaTransitionViolation = validateIdeaTransitionTitle(artifact, ideasPath, fileSystem);
+    if (ideaTransitionViolation)
+      violations.push(ideaTransitionViolation);
+    violations.push(...validateWorkflowTaskBodySection(artifact, ideasPath, fileSystem));
+  }
+  const allPrincipleRelationships = [];
+  for (const artifact of byType.principles) {
+    violations.push(...validatePrincipleHierarchySections(artifact));
+    violations.push(...validatePrincipleHierarchyLinks(artifact));
+    allPrincipleRelationships.push(extractPrincipleRelationships(artifact));
+  }
+  violations.push(...validateBidirectionalLinks(allPrincipleRelationships));
+  violations.push(...validateNoCycles(allPrincipleRelationships));
+  return violations;
+}
+
+// lib/validation/index.ts
+var ALLOWED_ROOT_DIRECTORIES = [
+  "config",
+  "facts",
+  "ideas",
+  "principles",
+  "tasks"
+];
+var ALLOWED_ROOT_FILES = ["repository.md"];
+var ALLOWED_ROOT_PATHS = [
+  ...ALLOWED_ROOT_DIRECTORIES.map((directory) => `${directory}/`),
+  ...ALLOWED_ROOT_FILES
+].join(", ");
+function validatePatchRootEntries(fileSystem, dustPath, patch) {
+  const violations = [];
+  const sortedPaths = Object.keys(patch.files).toSorted();
+  const reportedUnexpectedRootDirectories = new Set;
+  for (const relativePath of sortedPaths) {
+    const content = patch.files[relativePath];
+    if (content === null)
+      continue;
+    const [rootEntry] = relativePath.split("/");
+    if (!rootEntry)
+      continue;
+    if (ALLOWED_ROOT_DIRECTORIES.includes(rootEntry) || ALLOWED_ROOT_FILES.includes(rootEntry)) {
+      continue;
+    }
+    const rootEntryPath = `${dustPath}/${rootEntry}`;
+    if (relativePath.includes("/")) {
+      if (!reportedUnexpectedRootDirectories.has(rootEntry) && !fileSystem.isDirectory(rootEntryPath)) {
+        violations.push({
+          file: rootEntryPath,
+          message: `Unexpected directory "${rootEntry}" in .dust/. Allowed root paths: ${ALLOWED_ROOT_PATHS}`
+        });
+        reportedUnexpectedRootDirectories.add(rootEntry);
+      }
+      continue;
+    }
+    violations.push({
+      file: rootEntryPath,
+      message: `Unexpected file "${rootEntry}" in .dust/. Allowed root paths: ${ALLOWED_ROOT_PATHS}`
+    });
+  }
+  return violations;
+}
+function relativizeViolationFilePath(filePath, cwd) {
+  const relativePath = relative(cwd, filePath);
+  if (relativePath === "" || relativePath === "." || relativePath === ".." || relativePath.startsWith("../") || relativePath.startsWith("..\\")) {
+    return filePath;
+  }
+  return relativePath;
+}
+function relativizeViolations(violations, cwd) {
+  return violations.map((violation) => ({
+    ...violation,
+    file: relativizeViolationFilePath(violation.file, cwd)
+  }));
+}
+function parsePatchFiles(dustPath, patch) {
+  const absolutePatchFiles = new Map;
+  const deletedPaths = new Set;
+  for (const [relativePath, content] of Object.entries(patch.files)) {
+    const absolutePath = `${dustPath}/${relativePath}`;
+    if (content === null) {
+      deletedPaths.add(absolutePath);
+    } else {
+      absolutePatchFiles.set(absolutePath, content);
+    }
+  }
+  return { absolutePatchFiles, deletedPaths };
+}
+async function validatePatch(fileSystem, dustPath, patch, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const { absolutePatchFiles, deletedPaths } = parsePatchFiles(dustPath, patch);
+  const overlayFs = createOverlayFileSystem(fileSystem, absolutePatchFiles, deletedPaths);
+  const violations = [];
+  violations.push(...validatePatchRootEntries(fileSystem, dustPath, patch));
+  const { context, violations: parseViolations } = await parseArtifacts(overlayFs, dustPath);
+  violations.push(...parseViolations);
+  violations.push(...validateArtifacts(context));
+  return {
+    valid: violations.length === 0,
+    violations: relativizeViolations(violations, cwd)
+  };
+}
+
+// lib/patch/fact.ts
+function serializeFact(input) {
+  return `# ${input.title}
+
+${input.body}
+`;
+}
+function buildFactFiles(input, slug) {
+  const content = serializeFact(input);
+  return {
+    [`facts/${slug}.md`]: content
+  };
+}
+
+// lib/patch/idea.ts
+function renderOpenQuestionsSection(openQuestions) {
+  const parts = ["## Open Questions", ""];
+  for (const q of openQuestions) {
+    parts.push(`### ${q.question}`);
+    parts.push("");
+    for (const o of q.options) {
+      parts.push(`#### ${o.name}`);
+      parts.push("");
+      if (o.description) {
+        parts.push(o.description);
+        parts.push("");
+      }
+    }
+  }
+  return parts.join(`
+`);
+}
+function serializeIdea(input) {
+  const parts = [];
+  parts.push(`# ${input.title}`);
+  parts.push("");
+  if (input.body) {
+    parts.push(input.body.trimEnd());
+    parts.push("");
+  }
+  if (input.openQuestions && input.openQuestions.length > 0) {
+    parts.push(renderOpenQuestionsSection(input.openQuestions));
+  }
+  return parts.join(`
+`);
+}
+function buildIdeaFiles(input, slug) {
+  const content = serializeIdea(input);
+  return {
+    [`ideas/${slug}.md`]: content
+  };
+}
+
+// lib/patch/principle.ts
+function slugToTitle(slug) {
+  return slug.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+function renderParentPrincipleSection(parentPrinciple) {
+  if (parentPrinciple === null || parentPrinciple === undefined) {
+    return `## Parent Principle
+
+- (none)
+`;
+  }
+  const title = slugToTitle(parentPrinciple);
+  return `## Parent Principle
+
+- [${title}](${parentPrinciple}.md)
+`;
+}
+function renderSubPrinciplesSection(subPrinciples) {
+  if (subPrinciples.length === 0) {
+    return `## Sub-Principles
+
+- (none)
+`;
+  }
+  const links = subPrinciples.map((slug) => {
+    const title = slugToTitle(slug);
+    return `- [${title}](${slug}.md)`;
+  });
+  return `## Sub-Principles
+
+${links.join(`
+`)}
+`;
+}
+function serializePrinciple(input) {
+  const sections = [];
+  sections.push(`# ${input.title}`);
+  if (input.body) {
+    sections.push(input.body);
+  }
+  sections.push(renderParentPrincipleSection(input.parentPrinciple ?? null));
+  sections.push(renderSubPrinciplesSection(input.subPrinciples ?? []));
+  return sections.join(`
+
+`);
+}
+function buildPrincipleFiles(input, slug) {
+  const content = serializePrinciple(input);
+  return {
+    [`principles/${slug}.md`]: content
+  };
+}
+
+// lib/patch/task.ts
+var WORKFLOW_SECTION_HEADINGS = {
+  "capture-idea": "Captures Idea",
+  "refine-idea": "Refines Idea",
+  "decompose-idea": "Decomposes Idea",
+  "shelve-idea": "Shelves Idea"
+};
+var WORKFLOW_TITLE_PREFIXES = {
+  "capture-idea": "Add Idea: ",
+  "refine-idea": "Refine Idea: ",
+  "decompose-idea": "Decompose Idea: ",
+  "shelve-idea": "Shelve Idea: "
+};
+var WORKFLOW_OPENING_SENTENCES = {
+  "capture-idea": "Research this idea thoroughly and create an idea file.",
+  "refine-idea": "Thoroughly research this idea and refine it into a well-defined proposal.",
+  "decompose-idea": "Create one or more well-defined tasks from this idea.",
+  "shelve-idea": "Archive this idea and remove it from the active backlog."
+};
+var WORKFLOW_DEFAULT_DEFINITION_OF_DONE = {
+  "capture-idea": ["Idea file is created in .dust/ideas/"],
+  "refine-idea": [
+    "Idea is thoroughly researched with relevant codebase context"
+  ],
+  "decompose-idea": ["One or more new tasks are created in .dust/tasks/"],
+  "shelve-idea": ["Idea file is deleted"]
+};
+function ideaSlugToTitle(slug) {
+  return slug.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+function renderPrinciplesSection(principles) {
+  const links = principles.map((slug) => `- [${ideaSlugToTitle(slug)}](../principles/${slug}.md)`);
+  return `## Principles
+
+${links.join(`
+`)}
+`;
+}
+function renderBlockedBySection(blockedBy) {
+  if (blockedBy.length === 0) {
+    return `## Blocked By
+
+(none)
+`;
+  }
+  const links = blockedBy.map((slug) => `- [${ideaSlugToTitle(slug)}](${slug}.md)`);
+  return `## Blocked By
+
+${links.join(`
+`)}
+`;
+}
+function renderDefinitionOfDoneSection(items) {
+  return `## Definition of Done
+
+${items.map((item) => `- ${item}`).join(`
+`)}
+`;
+}
+function serializeStandardTask(input) {
+  const sections = [];
+  sections.push(`# ${input.title}`);
+  if (input.body) {
+    sections.push(input.body);
+  }
+  if (input.principles && input.principles.length > 0) {
+    sections.push(renderPrinciplesSection(input.principles));
+  }
+  sections.push(renderBlockedBySection(input.blockedBy ?? []));
+  sections.push(renderDefinitionOfDoneSection(input.definitionOfDone));
+  return sections.join(`
+
+`);
+}
+function serializeWorkflowTask(input) {
+  const ideaTitle = ideaSlugToTitle(input.ideaSlug);
+  const prefix = WORKFLOW_TITLE_PREFIXES[input.type];
+  const title = `${prefix}${ideaTitle}`;
+  const openingSentence = WORKFLOW_OPENING_SENTENCES[input.type];
+  const sectionHeading = WORKFLOW_SECTION_HEADINGS[input.type];
+  const definitionOfDone = input.definitionOfDone ?? WORKFLOW_DEFAULT_DEFINITION_OF_DONE[input.type];
+  const ideaSection = `## ${sectionHeading}
+
+- [${ideaTitle}](../ideas/${input.ideaSlug}.md)`;
+  return `# ${title}
+
+${openingSentence}
+
+${ideaSection}
+
+## Blocked By
+
+(none)
+
+## Definition of Done
+
+${definitionOfDone.map((item) => `- ${item}`).join(`
+`)}
+`;
+}
+function serializeTask(input) {
+  if (input.type) {
+    return serializeWorkflowTask(input);
+  }
+  return serializeStandardTask(input);
+}
+function buildTaskFiles(input, slug) {
+  const content = serializeTask(input);
+  return {
+    [`tasks/${slug}.md`]: content
+  };
+}
+
+// lib/patch/index.ts
+var CONTENT_DIRS2 = ["principles", "facts", "ideas", "tasks"];
+function validatePrincipleHierarchy(principles, existingPrinciples, deletedPrinciples) {
+  const violations = [];
+  const allPrinciples = new Map;
+  for (const [slug, rel] of existingPrinciples) {
+    if (!deletedPrinciples.has(slug)) {
+      allPrinciples.set(slug, rel);
+    }
+  }
+  for (const [slug, input] of Object.entries(principles)) {
+    allPrinciples.set(slug, {
+      slug,
+      parentPrinciple: input.parentPrinciple ?? null,
+      subPrinciples: input.subPrinciples ?? []
+    });
+  }
+  for (const [slug, rel] of allPrinciples) {
+    const filePath = `principles/${slug}.md`;
+    if (rel.parentPrinciple !== null) {
+      const parent = allPrinciples.get(rel.parentPrinciple);
+      if (parent && !parent.subPrinciples.includes(slug)) {
+        violations.push({
+          file: filePath,
+          message: `Parent principle "${rel.parentPrinciple}" does not list this principle as a sub-principle`
+        });
+      }
+    }
+    for (const subSlug of rel.subPrinciples) {
+      const child = allPrinciples.get(subSlug);
+      if (child && child.parentPrinciple !== slug) {
+        violations.push({
+          file: filePath,
+          message: `Sub-principle "${subSlug}" does not list this principle as its parent`
+        });
+      }
+    }
+  }
+  return violations;
+}
+async function loadExistingPrincipleRelationships(fileSystem, dustPath) {
+  const relationships = new Map;
+  const principlesDir = `${dustPath}/principles`;
+  let entries;
+  try {
+    entries = await fileSystem.readdir(principlesDir);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return relationships;
+    }
+    throw error;
+  }
+  for (const entry of entries) {
+    if (!entry.endsWith(".md"))
+      continue;
+    const slug = entry.slice(0, -3);
+    const filePath = `${principlesDir}/${entry}`;
+    const content = await fileSystem.readFile(filePath);
+    const rel = parsePrincipleRelationships(content, slug);
+    relationships.set(slug, rel);
+  }
+  return relationships;
+}
+function parsePrincipleRelationships(content, slug) {
+  const parentPrinciple = extractSingleSlugFromSection(content, "Parent Principle");
+  const subPrinciples = extractSlugsFromSection(content, "Sub-Principles");
+  return { slug, parentPrinciple, subPrinciples };
+}
+function extractSingleSlugFromSection(content, sectionHeading) {
+  const slugs = extractSlugsFromSection(content, sectionHeading);
+  return slugs.length === 1 ? slugs[0] : null;
+}
+function extractSlugsFromSection(content, sectionHeading) {
+  const lines = content.split(`
+`);
+  const slugs = [];
+  let inSection = false;
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      inSection = line.trimEnd() === `## ${sectionHeading}`;
+      continue;
+    }
+    if (!inSection)
+      continue;
+    if (line.startsWith("# "))
+      break;
+    const linkMatch = line.match(MARKDOWN_LINK_PATTERN2);
+    if (linkMatch) {
+      const target = linkMatch[2];
+      const slugMatch = target.match(/([^/]+)\.md$/);
+      if (slugMatch) {
+        slugs.push(slugMatch[1]);
+      }
+    }
+  }
+  return slugs;
+}
+function updatePrincipleHierarchyOnDeletion(content, deletedPaths, sourceFilePath) {
+  return cleanupPrincipleHierarchySections(removeLinksToDeletedPaths(content, deletedPaths, sourceFilePath));
+}
+function cleanupPrincipleHierarchySections(content) {
+  const lines = content.split(`
+`);
+  const result = [];
+  let inHierarchySection = false;
+  let hierarchySectionHeading = "";
+  let sectionItems = [];
+  let hasValidContent = false;
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith("## ")) {
+      if (inHierarchySection) {
+        result.push(hierarchySectionHeading, "");
+        if (hasValidContent) {
+          result.push(...sectionItems.filter((item) => MARKDOWN_LINK_PATTERN2.test(item)));
+        } else {
+          result.push("- (none)");
+        }
+        inHierarchySection = false;
+        sectionItems = [];
+        hasValidContent = false;
+      }
+      const heading = line.trimEnd();
+      if (heading === "## Parent Principle" || heading === "## Sub-Principles") {
+        inHierarchySection = true;
+        hierarchySectionHeading = heading;
+        continue;
+      }
+    }
+    if (inHierarchySection) {
+      if (line.startsWith("- ")) {
+        sectionItems.push(line);
+        if (MARKDOWN_LINK_PATTERN2.test(line)) {
+          hasValidContent = true;
+        }
+      } else if (line.trim() === "(none)") {} else if (line.trim() !== "") {
+        sectionItems.push(line);
+        hasValidContent = true;
+      }
+      continue;
+    }
+    result.push(line);
+  }
+  if (inHierarchySection) {
+    result.push(hierarchySectionHeading, "");
+    if (hasValidContent) {
+      result.push(...sectionItems.filter((item) => MARKDOWN_LINK_PATTERN2.test(item)));
+    } else {
+      result.push("- (none)");
+    }
+  }
+  return result.join(`
+`);
+}
+async function findReferencesToDeletedPaths(fileSystem, dustPath, deletedPaths) {
+  const updates = new Map;
+  for (const dir of CONTENT_DIRS2) {
+    const dirPath = `${dustPath}/${dir}`;
+    let entries;
+    try {
+      entries = await fileSystem.readdir(dirPath);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        continue;
+      }
+      throw error;
+    }
+    for (const entry of entries) {
+      if (!entry.endsWith(".md"))
+        continue;
+      const filePath = `${dirPath}/${entry}`;
+      const relativePath = `${dir}/${entry}`;
+      if (deletedPaths.has(relativePath))
+        continue;
+      const content = await fileSystem.readFile(filePath);
+      const updatedContent = removeLinksToDeletedPaths(content, deletedPaths, relativePath);
+      if (updatedContent !== content) {
+        updates.set(relativePath, updatedContent);
+      }
+    }
+  }
+  return updates;
+}
+function removeLinksToDeletedPaths(content, deletedPaths, sourceFilePath) {
+  const globalPattern = new RegExp(MARKDOWN_LINK_PATTERN2.source, "g");
+  const sourceDir = sourceFilePath.substring(0, sourceFilePath.lastIndexOf("/"));
+  let linksRemoved = false;
+  let result = content.replace(globalPattern, (match, text, target) => {
+    const normalizedTarget = normalizeTargetPath(target, sourceDir);
+    if (normalizedTarget !== null && deletedPaths.has(normalizedTarget)) {
+      linksRemoved = true;
+      return text;
+    }
+    return match;
+  });
+  if (linksRemoved) {
+    result = cleanupBlockedBySection(result);
+  }
+  return result;
+}
+function filterBlockedByItems(items) {
+  return items.filter((item) => MARKDOWN_LINK_PATTERN2.test(item));
+}
+function renderBlockedByContent(heading, items, hasRealContent) {
+  const result = [heading];
+  if (hasRealContent) {
+    result.push(...filterBlockedByItems(items));
+  } else {
+    result.push("", "(none)");
+  }
+  return result;
+}
+function cleanupBlockedBySection(content) {
+  const lines = content.split(`
+`);
+  const result = [];
+  let inBlockedBy = false;
+  let blockedByStart = -1;
+  let blockedByItems = [];
+  let hasRealContent = false;
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith("## ")) {
+      if (inBlockedBy) {
+        const sectionLines = renderBlockedByContent(lines[blockedByStart], blockedByItems, hasRealContent);
+        result.push(...sectionLines);
+        inBlockedBy = false;
+        blockedByItems = [];
+        hasRealContent = false;
+      }
+      if (line.trimEnd() === "## Blocked By") {
+        inBlockedBy = true;
+        blockedByStart = i;
+        continue;
+      }
+    }
+    if (inBlockedBy) {
+      if (line.startsWith("- ")) {
+        blockedByItems.push(line);
+        if (MARKDOWN_LINK_PATTERN2.test(line)) {
+          hasRealContent = true;
+        }
+      } else if (line.trim() === "(none)") {
+        hasRealContent = false;
+      } else if (line.trim() !== "") {
+        blockedByItems.push(line);
+        hasRealContent = true;
+      }
+      continue;
+    }
+    result.push(line);
+  }
+  if (inBlockedBy) {
+    const sectionLines = renderBlockedByContent(lines[blockedByStart], blockedByItems, hasRealContent);
+    result.push(...sectionLines);
+  }
+  return result.join(`
+`);
+}
+function normalizeTargetPath(target, sourceDir) {
+  if (target.startsWith("http://") || target.startsWith("https://")) {
+    return null;
+  }
+  if (target.startsWith("../") || target.startsWith("./")) {
+    const parts = [...sourceDir.split("/"), ...target.split("/")];
+    const resolved = [];
+    for (const part of parts) {
+      if (part === "..") {
+        resolved.pop();
+      } else if (part !== "." && part !== "") {
+        resolved.push(part);
+      }
+    }
+    return resolved.join("/");
+  }
+  if (!target.includes("/")) {
+    return `${sourceDir}/${target}`;
+  }
+  if (target.startsWith("facts/") || target.startsWith("ideas/") || target.startsWith("tasks/") || target.startsWith("principles/")) {
+    return target;
+  }
+  return null;
+}
+function processFacts(facts, accumulator) {
+  for (const [slug, factInput] of Object.entries(facts)) {
+    if (factInput === null) {
+      const relativePath = `facts/${slug}.md`;
+      accumulator.files[relativePath] = null;
+      accumulator.deletedPaths.add(relativePath);
+    } else {
+      const factFiles = buildFactFiles(factInput, slug);
+      Object.assign(accumulator.files, factFiles);
+    }
+  }
+}
+function processTasks(tasks, accumulator) {
+  for (const [slug, taskInput] of Object.entries(tasks)) {
+    if (taskInput === null) {
+      const relativePath = `tasks/${slug}.md`;
+      accumulator.files[relativePath] = null;
+      accumulator.deletedPaths.add(relativePath);
+    } else {
+      const taskFiles = buildTaskFiles(taskInput, slug);
+      Object.assign(accumulator.files, taskFiles);
+    }
+  }
+}
+function processIdeas(ideas, accumulator) {
+  for (const [slug, ideaInput] of Object.entries(ideas)) {
+    if (ideaInput === null) {
+      const relativePath = `ideas/${slug}.md`;
+      accumulator.files[relativePath] = null;
+      accumulator.deletedPaths.add(relativePath);
+    } else {
+      const ideaFiles = buildIdeaFiles(ideaInput, slug);
+      Object.assign(accumulator.files, ideaFiles);
+    }
+  }
+}
+async function processPrinciples(fileSystem, dustPath, principles, accumulator) {
+  const deletedSlugs = new Set;
+  const hierarchyViolations = [];
+  const existingPrinciples = await loadExistingPrincipleRelationships(fileSystem, dustPath);
+  const principleUpdates = {};
+  for (const [slug, principleInput] of Object.entries(principles)) {
+    if (principleInput === null) {
+      const relativePath = `principles/${slug}.md`;
+      accumulator.files[relativePath] = null;
+      accumulator.deletedPaths.add(relativePath);
+      deletedSlugs.add(slug);
+    } else {
+      principleUpdates[slug] = principleInput;
+      const principleFiles = buildPrincipleFiles(principleInput, slug);
+      Object.assign(accumulator.files, principleFiles);
+    }
+  }
+  if (Object.keys(principleUpdates).length > 0) {
+    hierarchyViolations.push(...validatePrincipleHierarchy(principleUpdates, existingPrinciples, deletedSlugs));
+  }
+  if (deletedSlugs.size > 0) {
+    await updateRelatedPrinciplesOnDeletion(fileSystem, dustPath, existingPrinciples, deletedSlugs, accumulator);
+  }
+  return { deletedSlugs, hierarchyViolations };
+}
+async function updateRelatedPrinciplesOnDeletion(fileSystem, dustPath, existingPrinciples, deletedSlugs, accumulator) {
+  const deletedPaths = new Set([...deletedSlugs].map((slug) => `principles/${slug}.md`));
+  for (const [slug, rel] of existingPrinciples) {
+    if (deletedSlugs.has(slug))
+      continue;
+    const relativePath = `principles/${slug}.md`;
+    if (relativePath in accumulator.files)
+      continue;
+    const referencesDeleted = rel.parentPrinciple !== null && deletedSlugs.has(rel.parentPrinciple) || rel.subPrinciples.some((sub) => deletedSlugs.has(sub));
+    if (referencesDeleted) {
+      const filePath = `${dustPath}/${relativePath}`;
+      const content = await fileSystem.readFile(filePath);
+      const updatedContent = updatePrincipleHierarchyOnDeletion(content, deletedPaths, relativePath);
+      if (updatedContent !== content) {
+        accumulator.files[relativePath] = updatedContent;
+      }
+    }
+  }
+}
+async function buildArtifactPatch(fileSystem, dustPath, input, options = {}) {
+  const accumulator = {
+    files: {},
+    deletedPaths: new Set
+  };
+  let hierarchyViolations = [];
+  if (input.facts) {
+    processFacts(input.facts, accumulator);
+  }
+  if (input.ideas) {
+    processIdeas(input.ideas, accumulator);
+  }
+  if (input.principles) {
+    const result = await processPrinciples(fileSystem, dustPath, input.principles, accumulator);
+    hierarchyViolations = result.hierarchyViolations;
+  }
+  if (input.tasks) {
+    processTasks(input.tasks, accumulator);
+  }
+  if (accumulator.deletedPaths.size > 0) {
+    const referenceUpdates = await findReferencesToDeletedPaths(fileSystem, dustPath, accumulator.deletedPaths);
+    for (const [path, content] of referenceUpdates) {
+      if (!(path in accumulator.files)) {
+        accumulator.files[path] = content;
+      }
+    }
+  }
+  const patch = { files: accumulator.files };
+  const validationResult = await validatePatch(fileSystem, dustPath, patch, options);
+  return {
+    valid: validationResult.valid && hierarchyViolations.length === 0,
+    violations: [...hierarchyViolations, ...validationResult.violations],
+    patch
+  };
+}
+export {
+  serializeTask,
+  serializePrinciple,
+  serializeIdea,
+  serializeFact,
+  buildArtifactPatch
+};