@joshski/dust 0.1.73 → 0.1.75

package/dist/artifacts/index.d.ts

@@ -3,9 +3,9 @@ import { type Fact } from './facts';
 import { type Idea, type IdeaOpenQuestion, type IdeaOption, parseOpenQuestions } from './ideas';
 import { type Principle } from './principles';
 import { type Task } from './tasks';
-import { type AllWorkflowTasks, CAPTURE_IDEA_PREFIX, type CreateIdeaTransitionTaskResult, type DecomposeIdeaOptions, findAllCaptureIdeaTasks, findAllWorkflowTasks, type IdeaInProgress, type OpenQuestionResponse, type ParsedCaptureIdeaTask, type WorkflowTaskMatch } from './workflow-tasks';
+import { type AllWorkflowTasks, CAPTURE_IDEA_PREFIX, type CreateIdeaTransitionTaskResult, type DecomposeIdeaOptions, findAllWorkflowTasks, type IdeaInProgress, type OpenQuestionResponse, type ParsedCaptureIdeaTask, type WorkflowTaskMatch } from './workflow-tasks';
 export type { AllWorkflowTasks, CreateIdeaTransitionTaskResult, DecomposeIdeaOptions, Fact, Idea, IdeaOpenQuestion, IdeaOption, OpenQuestionResponse, ParsedCaptureIdeaTask, Principle, Task, WorkflowTaskMatch, };
-export { CAPTURE_IDEA_PREFIX, findAllCaptureIdeaTasks, findAllWorkflowTasks, parseOpenQuestions, };
+export { CAPTURE_IDEA_PREFIX, findAllWorkflowTasks, parseOpenQuestions };
 export type { IdeaInProgress };
 export interface ArtifactsRepository {
     parseIdea(options: {
@@ -27,16 +27,21 @@ export interface ArtifactsRepository {
     createRefineIdeaTask(options: {
         ideaSlug: string;
         description?: string;
+        dustCommand?: string;
+    }): Promise<CreateIdeaTransitionTaskResult>;
+    createDecomposeIdeaTask(options: DecomposeIdeaOptions & {
+        dustCommand?: string;
     }): Promise<CreateIdeaTransitionTaskResult>;
-    createDecomposeIdeaTask(options: DecomposeIdeaOptions): Promise<CreateIdeaTransitionTaskResult>;
     createShelveIdeaTask(options: {
         ideaSlug: string;
         description?: string;
+        dustCommand?: string;
     }): Promise<CreateIdeaTransitionTaskResult>;
     createIdeaTask(options: {
         title: string;
         description: string;
         expedite?: boolean;
+        dustCommand?: string;
     }): Promise<CreateIdeaTransitionTaskResult>;
     findWorkflowTaskForIdea(options: {
         ideaSlug: string;

package/dist/artifacts/workflow-tasks.d.ts

@@ -11,7 +11,6 @@ export interface ParsedCaptureIdeaTask {
     ideaDescription: string;
     expedite: boolean;
 }
-export declare function findAllCaptureIdeaTasks(fileSystem: ReadableFileSystem, dustPath: string): Promise<IdeaInProgress[]>;
 /**
  * Converts a markdown title to the expected filename using deterministic rules:
  * 1. Convert to lowercase
@@ -46,12 +45,13 @@ export interface DecomposeIdeaOptions {
     description?: string;
     openQuestionResponses?: OpenQuestionResponse[];
 }
-export declare function createRefineIdeaTask(fileSystem: FileSystem, dustPath: string, ideaSlug: string, description?: string): Promise<CreateIdeaTransitionTaskResult>;
-export declare function decomposeIdea(fileSystem: FileSystem, dustPath: string, options: DecomposeIdeaOptions): Promise<CreateIdeaTransitionTaskResult>;
-export declare function createShelveIdeaTask(fileSystem: FileSystem, dustPath: string, ideaSlug: string, description?: string): Promise<CreateIdeaTransitionTaskResult>;
+export declare function createRefineIdeaTask(fileSystem: FileSystem, dustPath: string, ideaSlug: string, description?: string, dustCommand?: string): Promise<CreateIdeaTransitionTaskResult>;
+export declare function decomposeIdea(fileSystem: FileSystem, dustPath: string, options: DecomposeIdeaOptions, dustCommand?: string): Promise<CreateIdeaTransitionTaskResult>;
+export declare function createShelveIdeaTask(fileSystem: FileSystem, dustPath: string, ideaSlug: string, description?: string, _dustCommand?: string): Promise<CreateIdeaTransitionTaskResult>;
 export declare function createIdeaTask(fileSystem: FileSystem, dustPath: string, options: {
     title: string;
     description: string;
     expedite?: boolean;
+    dustCommand?: string;
 }): Promise<CreateIdeaTransitionTaskResult>;
 export declare function parseCaptureIdeaTask(fileSystem: ReadableFileSystem, dustPath: string, taskSlug: string): Promise<ParsedCaptureIdeaTask | null>;

package/dist/artifacts.js

@@ -273,32 +273,6 @@ async function parseTask(fileSystem, dustPath, slug) {
 // lib/artifacts/workflow-tasks.ts
 var CAPTURE_IDEA_PREFIX = "Add Idea: ";
 var EXPEDITE_IDEA_PREFIX = "Expedite Idea: ";
-async function findAllCaptureIdeaTasks(fileSystem, dustPath) {
-  const tasksPath = `${dustPath}/tasks`;
-  if (!fileSystem.exists(tasksPath))
-    return [];
-  const files = await fileSystem.readdir(tasksPath);
-  const results = [];
-  for (const file of files.filter((f) => f.endsWith(".md")).sort()) {
-    const content = await fileSystem.readFile(`${tasksPath}/${file}`);
-    const titleMatch = content.match(/^#\s+(.+)$/m);
-    if (!titleMatch)
-      continue;
-    const title = titleMatch[1].trim();
-    if (title.startsWith(CAPTURE_IDEA_PREFIX)) {
-      results.push({
-        taskSlug: file.replace(/\.md$/, ""),
-        ideaTitle: title.slice(CAPTURE_IDEA_PREFIX.length)
-      });
-    } else if (title.startsWith(EXPEDITE_IDEA_PREFIX)) {
-      results.push({
-        taskSlug: file.replace(/\.md$/, ""),
-        ideaTitle: title.slice(EXPEDITE_IDEA_PREFIX.length)
-      });
-    }
-  }
-  return results;
-}
 function titleToFilename(title) {
   return `${title.toLowerCase().replace(/\./g, "-").replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "")}.md`;
 }
@@ -458,16 +432,18 @@ async function createIdeaTransitionTask(fileSystem, dustPath, prefix, ideaSlug,
   await fileSystem.writeFile(filePath, content);
   return { filePath };
 }
-async function createRefineIdeaTask(fileSystem, dustPath, ideaSlug, description) {
-  return createIdeaTransitionTask(fileSystem, dustPath, "Refine Idea: ", ideaSlug, (ideaTitle) => `Thoroughly research this idea and refine it into a well-defined proposal. Read the idea file, explore the codebase for relevant context, and identify any ambiguity. Where aspects are unclear or could go multiple ways, add open questions to the idea file. Review \`.dust/principles/\` for alignment and \`.dust/facts/\` for relevant design decisions. See [${ideaTitle}](../ideas/${ideaSlug}.md). If you add open questions, use \`## Open Questions\` with \`### Question?\` headings and one or more \`#### Option\` headings beneath each question, and only add questions that are meaningful decisions worth asking.`, [
+async function createRefineIdeaTask(fileSystem, dustPath, ideaSlug, description, dustCommand) {
+  const cmd = dustCommand ?? "dust";
+  return createIdeaTransitionTask(fileSystem, dustPath, "Refine Idea: ", ideaSlug, (ideaTitle) => `Thoroughly research this idea and refine it into a well-defined proposal. Read the idea file, explore the codebase for relevant context, and identify any ambiguity. Where aspects are unclear or could go multiple ways, add open questions to the idea file. Run \`${cmd} principles\` for alignment and \`${cmd} facts\` for relevant design decisions. See [${ideaTitle}](../ideas/${ideaSlug}.md). If you add open questions, use \`## Open Questions\` with \`### Question?\` headings and one or more \`#### Option\` headings beneath each question, and only add questions that are meaningful decisions worth asking.`, [
     "Idea is thoroughly researched with relevant codebase context",
     "Open questions are added for any ambiguous or underspecified aspects",
     "Open questions follow the required heading format and focus on high-value decisions",
     "Idea file is updated with findings"
   ], "Refines Idea", { description });
 }
-async function decomposeIdea(fileSystem, dustPath, options) {
-  return createIdeaTransitionTask(fileSystem, dustPath, "Decompose Idea: ", options.ideaSlug, (ideaTitle) => `Create one or more well-defined tasks from this idea. Prefer smaller, narrowly scoped tasks that each deliver a thin but complete vertical slice of working software -- a path through the system that can be tested end-to-end -- rather than component-oriented tasks (like "add schema" or "build endpoint") that only work once all tasks are done. Split the idea into multiple tasks if it covers more than one logical change. Review \`.dust/principles/\` to link relevant principles and \`.dust/facts/\` for design decisions that should inform the task. See [${ideaTitle}](../ideas/${options.ideaSlug}.md).`, [
+async function decomposeIdea(fileSystem, dustPath, options, dustCommand) {
+  const cmd = dustCommand ?? "dust";
+  return createIdeaTransitionTask(fileSystem, dustPath, "Decompose Idea: ", options.ideaSlug, (ideaTitle) => `Create one or more well-defined tasks from this idea. Prefer smaller, narrowly scoped tasks that each deliver a thin but complete vertical slice of working software -- a path through the system that can be tested end-to-end -- rather than component-oriented tasks (like "add schema" or "build endpoint") that only work once all tasks are done. Split the idea into multiple tasks if it covers more than one logical change. Run \`${cmd} principles\` to link relevant principles and \`${cmd} facts\` for design decisions that should inform the task. See [${ideaTitle}](../ideas/${options.ideaSlug}.md).`, [
     "One or more new tasks are created in .dust/tasks/",
     "Task's Principles section links to relevant principles from .dust/principles/",
     "The original idea is deleted or updated to reflect remaining scope"
@@ -476,11 +452,12 @@ async function decomposeIdea(fileSystem, dustPath, options) {
     resolvedQuestions: options.openQuestionResponses
   });
 }
-async function createShelveIdeaTask(fileSystem, dustPath, ideaSlug, description) {
+async function createShelveIdeaTask(fileSystem, dustPath, ideaSlug, description, _dustCommand) {
   return createIdeaTransitionTask(fileSystem, dustPath, "Shelve Idea: ", ideaSlug, (ideaTitle) => `Archive this idea and remove it from the active backlog. See [${ideaTitle}](../ideas/${ideaSlug}.md).`, ["Idea file is deleted", "Rationale is recorded in the commit message"], "Shelves Idea", { description });
 }
 async function createIdeaTask(fileSystem, dustPath, options) {
-  const { title, description, expedite } = options;
+  const { title, description, expedite, dustCommand } = options;
+  const cmd = dustCommand ?? "dust";
   if (!title || !title.trim()) {
     throw new Error("title is required and must not be whitespace-only");
   }
@@ -493,7 +470,7 @@ async function createIdeaTask(fileSystem, dustPath, options) {
     const filePath2 = `${dustPath}/tasks/${filename2}`;
     const content2 = `# ${taskTitle2}
 
-Research this idea briefly. If confident the implementation is straightforward (clear scope, minimal risk, no open questions), implement directly and commit. Otherwise, create one or more narrowly-scoped task files in \`.dust/tasks/\`. Review \`.dust/principles/\` and \`.dust/facts/\` for relevant context.
+Research this idea briefly. If confident the implementation is straightforward (clear scope, minimal risk, no open questions), implement directly and commit. Otherwise, create one or more narrowly-scoped task files in \`.dust/tasks/\`. Run \`${cmd} principles\` and \`${cmd} facts\` for relevant context.
 
 ## Idea Description
 
@@ -517,7 +494,7 @@ ${description}
   const filePath = `${dustPath}/tasks/${filename}`;
   const content = `# ${taskTitle}
 
-Research this idea thoroughly, then create one or more idea files in \`.dust/ideas/\`. Read the codebase for relevant context, flesh out the description, and identify any ambiguity. Where aspects are unclear or could go multiple ways, add open questions to the idea file. If you add open questions, use \`## Open Questions\` with \`### Question?\` headings and one or more \`#### Option\` headings beneath each question, and only add questions that are meaningful decisions worth asking. Review \`.dust/principles/\` and \`.dust/facts/\` for relevant context.
+Research this idea thoroughly, then create one or more idea files in \`.dust/ideas/\`. Read the codebase for relevant context, flesh out the description, and identify any ambiguity. Where aspects are unclear or could go multiple ways, add open questions to the idea file. If you add open questions, use \`## Open Questions\` with \`### Question?\` headings and one or more \`#### Option\` headings beneath each question, and only add questions that are meaningful decisions worth asking. Run \`${cmd} principles\` and \`${cmd} facts\` for relevant context.
 
 ## Idea Description
 
@@ -616,13 +593,13 @@ function buildArtifactsRepository(fileSystem, dustPath) {
       return files.filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, "")).sort();
     },
     async createRefineIdeaTask(options) {
-      return createRefineIdeaTask(fileSystem, dustPath, options.ideaSlug, options.description);
+      return createRefineIdeaTask(fileSystem, dustPath, options.ideaSlug, options.description, options.dustCommand);
     },
     async createDecomposeIdeaTask(options) {
-      return decomposeIdea(fileSystem, dustPath, options);
+      return decomposeIdea(fileSystem, dustPath, options, options.dustCommand);
     },
     async createShelveIdeaTask(options) {
-      return createShelveIdeaTask(fileSystem, dustPath, options.ideaSlug, options.description);
+      return createShelveIdeaTask(fileSystem, dustPath, options.ideaSlug, options.description, options.dustCommand);
     },
     async createIdeaTask(options) {
       return createIdeaTask(fileSystem, dustPath, options);
@@ -692,7 +669,6 @@ function buildReadOnlyArtifactsRepository(fileSystem, dustPath) {
 export {
   parseOpenQuestions,
   findAllWorkflowTasks,
-  findAllCaptureIdeaTasks,
   buildReadOnlyArtifactsRepository,
   buildArtifactsRepository,
   CAPTURE_IDEA_PREFIX

package/dist/audits.js

@@ -670,6 +670,55 @@ function globalState() {
     - [ ] Proposed ideas for refactoring global state to explicit dependencies
   `;
 }
+function repositoryContext() {
+  return dedent`
+    # Repository Context
+
+    Compile or update \`.dust/repository.md\` with a high-level overview of the repository's purpose, capabilities, and design philosophy.
+
+    ## Purpose
+
+    The repository context document helps downstream agents quickly understand the project without reading individual files. It describes features, scenarios, and design philosophy rather than implementation details. This enables high-level planning where agents reason about capabilities rather than code structure.
+
+    ## Scope
+
+    Review the current state of the codebase and produce a document covering:
+
+    1. **What the project is** - A one-sentence summary of its purpose
+    2. **What it does** - The key capabilities and features it provides
+    3. **How it fits into workflows** - How users or other systems interact with it
+    4. **Design philosophy** - The guiding principles behind its architecture
+    5. **Key scenarios** - The main use cases or user journeys it supports
+
+    Avoid mentioning specific file paths, class names, or implementation details. Write for someone who needs to make high-level suggestions about the project's direction, not someone about to edit a specific file.
+
+    ## Analysis Steps
+
+    1. Read the existing \`.dust/repository.md\` if it exists
+    2. Review README, package.json, and top-level documentation for project purpose
+    3. Scan the codebase to understand features and capabilities
+    4. Review \`.dust/principles/\` for design philosophy
+    5. Review \`.dust/facts/\` for context on current state
+    6. Update \`.dust/repository.md\` with current findings, preserving any sections that are still accurate
+
+    ## Principles
+
+    (none)
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] \`.dust/repository.md\` exists and is up to date
+    - [ ] Document describes what the project does without referencing specific files
+    - [ ] Key capabilities and features are listed
+    - [ ] Design philosophy or guiding approach is captured
+    - [ ] Document is concise enough to fit comfortably in an agent context window
+    - [ ] A new agent reading only this document could make sensible high-level suggestions
+  `;
+}
 function ubiquitousLanguage() {
   return dedent`
     # Ubiquitous Language
@@ -736,6 +785,7 @@ var stockAuditFunctions = {
   "ideas-from-principles": ideasFromPrinciples,
   "performance-review": performanceReview,
   "refactoring-opportunities": refactoringOpportunities,
+  "repository-context": repositoryContext,
   "security-review": securityReview,
   "stale-ideas": staleIdeas,
   "test-coverage": testCoverage,

package/dist/dust.js

@@ -275,7 +275,7 @@ async function loadSettings(cwd, fileSystem) {
 }
 
 // lib/version.ts
-var DUST_VERSION = "0.1.73";
+var DUST_VERSION = "0.1.75";
 
 // lib/session.ts
 var DUST_UNATTENDED = "DUST_UNATTENDED";
@@ -1217,6 +1217,55 @@ function globalState() {
     - [ ] Proposed ideas for refactoring global state to explicit dependencies
   `;
 }
+function repositoryContext() {
+  return dedent`
+    # Repository Context
+
+    Compile or update \`.dust/repository.md\` with a high-level overview of the repository's purpose, capabilities, and design philosophy.
+
+    ## Purpose
+
+    The repository context document helps downstream agents quickly understand the project without reading individual files. It describes features, scenarios, and design philosophy rather than implementation details. This enables high-level planning where agents reason about capabilities rather than code structure.
+
+    ## Scope
+
+    Review the current state of the codebase and produce a document covering:
+
+    1. **What the project is** - A one-sentence summary of its purpose
+    2. **What it does** - The key capabilities and features it provides
+    3. **How it fits into workflows** - How users or other systems interact with it
+    4. **Design philosophy** - The guiding principles behind its architecture
+    5. **Key scenarios** - The main use cases or user journeys it supports
+
+    Avoid mentioning specific file paths, class names, or implementation details. Write for someone who needs to make high-level suggestions about the project's direction, not someone about to edit a specific file.
+
+    ## Analysis Steps
+
+    1. Read the existing \`.dust/repository.md\` if it exists
+    2. Review README, package.json, and top-level documentation for project purpose
+    3. Scan the codebase to understand features and capabilities
+    4. Review \`.dust/principles/\` for design philosophy
+    5. Review \`.dust/facts/\` for context on current state
+    6. Update \`.dust/repository.md\` with current findings, preserving any sections that are still accurate
+
+    ## Principles
+
+    (none)
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - [ ] \`.dust/repository.md\` exists and is up to date
+    - [ ] Document describes what the project does without referencing specific files
+    - [ ] Key capabilities and features are listed
+    - [ ] Design philosophy or guiding approach is captured
+    - [ ] Document is concise enough to fit comfortably in an agent context window
+    - [ ] A new agent reading only this document could make sensible high-level suggestions
+  `;
+}
 function ubiquitousLanguage() {
   return dedent`
     # Ubiquitous Language
@@ -1283,6 +1332,7 @@ var stockAuditFunctions = {
   "ideas-from-principles": ideasFromPrinciples,
   "performance-review": performanceReview,
   "refactoring-opportunities": refactoringOpportunities,
+  "repository-context": repositoryContext,
   "security-review": securityReview,
   "stale-ideas": staleIdeas,
   "test-coverage": testCoverage,

package/dist/lint/validators/content-validator.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Content validation for .dust markdown files
+ */
+import type { Violation } from './types';
+export declare function validateOpeningSentence(filePath: string, content: string): Violation | null;
+export declare function validateOpeningSentenceLength(filePath: string, content: string): Violation | null;
+export declare function validateImperativeOpeningSentence(filePath: string, content: string): Violation | null;
+export declare function validateTaskHeadings(filePath: string, content: string): Violation[];

package/dist/lint/validators/directory-validator.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Directory structure validation for .dust
+ */
+import type { ReadableFileSystem } from '../../filesystem/types';
+import type { Violation } from './types';
+export declare function validateContentDirectoryFiles(dirPath: string, fileSystem: ReadableFileSystem): Promise<Violation[]>;
+export declare function validateDirectoryStructure(dustPath: string, fileSystem: ReadableFileSystem, extraDirectories?: string[]): Promise<Violation[]>;

package/dist/lint/validators/filename-validator.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Filename validation for .dust markdown files
+ */
+import type { Violation } from './types';
+export declare function validateFilename(filePath: string): Violation | null;
+export declare function validateTitleFilenameMatch(filePath: string, content: string): Violation | null;

package/dist/lint/validators/idea-validator.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Idea file validation for .dust markdown files
+ */
+import type { ReadableFileSystem } from '../../filesystem/types';
+import type { Violation } from './types';
+export declare function validateIdeaOpenQuestions(filePath: string, content: string): Violation[];
+export declare function validateIdeaTransitionTitle(filePath: string, content: string, ideasPath: string, fileSystem: ReadableFileSystem): Violation | null;
+export declare function validateWorkflowTaskBodySection(filePath: string, content: string, ideasPath: string, fileSystem: ReadableFileSystem): Violation[];

package/dist/lint/validators/link-validator.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Link validation for .dust markdown files
+ */
+import type { ReadableFileSystem } from '../../filesystem/types';
+import type { Violation } from './types';
+export declare function validateLinks(filePath: string, content: string, fileSystem: ReadableFileSystem): Violation[];
+export declare function validateSemanticLinks(filePath: string, content: string): Violation[];
+export declare function validatePrincipleHierarchyLinks(filePath: string, content: string): Violation[];

package/dist/lint/validators/principle-hierarchy.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Principle hierarchy validation for .dust markdown files
+ */
+import type { PrincipleRelationships, Violation } from './types';
+export type { PrincipleRelationships };
+export declare function validatePrincipleHierarchySections(filePath: string, content: string): Violation[];
+export declare function extractPrincipleRelationships(filePath: string, content: string): PrincipleRelationships;
+export declare function validateBidirectionalLinks(allPrincipleRelationships: PrincipleRelationships[]): Violation[];
+export declare function validateNoCycles(allPrincipleRelationships: PrincipleRelationships[]): Violation[];

package/dist/lint/validators/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared types for lint validators
+ */
+export interface Violation {
+    file: string;
+    message: string;
+    line?: number;
+}
+export interface PrincipleRelationships {
+    filePath: string;
+    parentPrinciples: string[];
+    subPrinciples: string[];
+}

package/dist/validation/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Artifact patch validation API.
+ *
+ * Validates proposed artifact changes against existing .dust/ content
+ * using the same validators as `dust lint`.
+ */
+import type { ReadableFileSystem } from '../filesystem/types';
+import type { Violation } from '../lint/validators/types';
+export type { Violation } from '../lint/validators/types';
+export interface ArtifactPatch {
+    files: Record<string, string | null>;
+}
+export interface ValidationResult {
+    valid: boolean;
+    violations: Violation[];
+}
+/**
+ * Validates a patch of artifact changes against existing .dust/ content.
+ *
+ * @param fileSystem - The existing filesystem (e.g. from createFileSystemEmulator)
+ * @param dustPath - Absolute path to the .dust directory
+ * @param patch - Proposed new/changed files, with paths relative to dustPath
+ */
+export declare function validatePatch(fileSystem: ReadableFileSystem, dustPath: string, patch: ArtifactPatch): Promise<ValidationResult>;

package/dist/validation/overlay-filesystem.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Overlay filesystem that layers patch files over an existing ReadableFileSystem.
+ * Supports deletions via a set of paths to hide from the base filesystem.
+ */
+import type { ReadableFileSystem } from '../filesystem/types';
+export declare function createOverlayFileSystem(base: ReadableFileSystem, patchFiles: Map<string, string>, deletedPaths?: Set<string>): ReadableFileSystem;

package/dist/validation.js

@@ -0,0 +1,835 @@
+// lib/markdown/markdown-utilities.ts
+function extractTitle(content) {
+  const match = content.match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : null;
+}
+var MARKDOWN_LINK_PATTERN = /\[([^\]]+)\]\(([^)]+)\)/;
+function extractOpeningSentence(content) {
+  const lines = content.split(`
+`);
+  let h1Index = -1;
+  for (let i = 0;i < lines.length; i++) {
+    if (lines[i].match(/^#\s+.+$/)) {
+      h1Index = i;
+      break;
+    }
+  }
+  if (h1Index === -1) {
+    return null;
+  }
+  let paragraphStart = -1;
+  for (let i = h1Index + 1;i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line !== "") {
+      paragraphStart = i;
+      break;
+    }
+  }
+  if (paragraphStart === -1) {
+    return null;
+  }
+  const firstLine = lines[paragraphStart];
+  const trimmedFirstLine = firstLine.trim();
+  if (trimmedFirstLine.startsWith("#") || trimmedFirstLine.startsWith("-") || trimmedFirstLine.startsWith("*") || trimmedFirstLine.startsWith("+") || trimmedFirstLine.match(/^\d+\./) || trimmedFirstLine.startsWith("```") || trimmedFirstLine.startsWith(">")) {
+    return null;
+  }
+  let paragraph = "";
+  for (let i = paragraphStart;i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line === "")
+      break;
+    if (line.startsWith("#") || line.startsWith("```") || line.startsWith(">")) {
+      break;
+    }
+    paragraph += (paragraph ? " " : "") + line;
+  }
+  const sentenceMatch = paragraph.match(/^(.+?[.?!])(?:\s|$)/);
+  if (!sentenceMatch) {
+    return null;
+  }
+  return sentenceMatch[1];
+}
+
+// lib/lint/validators/content-validator.ts
+var REQUIRED_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(filePath, content) {
+  const openingSentence = extractOpeningSentence(content);
+  if (!openingSentence) {
+    return {
+      file: filePath,
+      message: "Missing or malformed opening sentence after H1 heading"
+    };
+  }
+  return null;
+}
+function validateOpeningSentenceLength(filePath, content) {
+  const openingSentence = extractOpeningSentence(content);
+  if (!openingSentence) {
+    return null;
+  }
+  if (openingSentence.length > MAX_OPENING_SENTENCE_LENGTH) {
+    return {
+      file: filePath,
+      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(filePath, content) {
+  const openingSentence = extractOpeningSentence(content);
+  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: filePath,
+      message: `Opening sentence should use imperative form (e.g., "Add X" not "This adds X"). Found: "${preview}"`
+    };
+  }
+  return null;
+}
+function validateTaskHeadings(filePath, content) {
+  const violations = [];
+  for (const heading of REQUIRED_HEADINGS) {
+    if (!content.includes(heading)) {
+      violations.push({
+        file: 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/artifacts/workflow-tasks.ts
+var IDEA_TRANSITION_PREFIXES = [
+  "Refine Idea: ",
+  "Decompose Idea: ",
+  "Shelve 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(filePath, content) {
+  const title = extractTitle(content);
+  if (!title) {
+    return null;
+  }
+  const parts = filePath.split("/");
+  const actualFilename = parts[parts.length - 1];
+  const expectedFilename = titleToFilename(title);
+  if (actualFilename !== expectedFilename) {
+    return {
+      file: 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"
+};
+function validateIdeaOpenQuestions(filePath, content) {
+  const violations = [];
+  const lines = content.split(`
+`);
+  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 (line.startsWith("## ")) {
+      if (inOpenQuestions && currentQuestionLine !== null) {
+        violations.push({
+          file: filePath,
+          message: "Question has no options listed beneath it",
+          line: currentQuestionLine
+        });
+      }
+      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: i + 1
+        });
+      }
+      inOpenQuestions = line === "## Open Questions";
+      currentQuestionLine = null;
+      inOption = false;
+      inCodeBlock = false;
+      continue;
+    }
+    if (!inOpenQuestions)
+      continue;
+    if (line.startsWith("```")) {
+      if (!inOption && !inCodeBlock) {
+        violations.push({
+          file: filePath,
+          message: topLevelStructureMessage,
+          line: i + 1
+        });
+      }
+      inCodeBlock = !inCodeBlock;
+      continue;
+    }
+    if (inCodeBlock)
+      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(filePath, content, ideasPath, fileSystem) {
+  const title = extractTitle(content);
+  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: filePath,
+          message: `Idea transition task references non-existent idea: "${ideaTitle}" (expected file "${ideaFilename}" in ideas/)`
+        };
+      }
+      return null;
+    }
+  }
+  return null;
+}
+function extractSectionContent(content, sectionHeading) {
+  const lines = content.split(`
+`);
+  let inSection = false;
+  let sectionContent = "";
+  let startLine = 0;
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith("## ")) {
+      if (inSection)
+        break;
+      if (line.trimEnd() === `## ${sectionHeading}`) {
+        inSection = true;
+        startLine = i + 1;
+      }
+      continue;
+    }
+    if (line.startsWith("# ") && inSection)
+      break;
+    if (inSection) {
+      sectionContent += `${line}
+`;
+    }
+  }
+  if (!inSection)
+    return null;
+  return { content: sectionContent, startLine };
+}
+function validateWorkflowTaskBodySection(filePath, content, ideasPath, fileSystem) {
+  const violations = [];
+  const title = extractTitle(content);
+  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 = extractSectionContent(content, expectedHeading);
+  if (!section) {
+    violations.push({
+      file: 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;
+  }
+  const linkRegex = new RegExp(MARKDOWN_LINK_PATTERN.source, "g");
+  const links = [];
+  const sectionLines = section.content.split(`
+`);
+  for (let i = 0;i < sectionLines.length; i++) {
+    const line = sectionLines[i];
+    let match = linkRegex.exec(line);
+    while (match !== null) {
+      links.push({
+        text: match[1],
+        target: match[2],
+        line: section.startLine + i + 1
+      });
+      match = linkRegex.exec(line);
+    }
+  }
+  if (links.length === 0) {
+    violations.push({
+      file: 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 = links.filter((l) => l.target.includes("/ideas/") || l.target.startsWith("../ideas/"));
+  if (ideaLinks.length === 0) {
+    violations.push({
+      file: 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: 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 = [
+  {
+    section: "## Principles",
+    requiredPath: "/.dust/principles/",
+    description: "principle"
+  },
+  {
+    section: "## Blocked By",
+    requiredPath: "/.dust/tasks/",
+    description: "task"
+  }
+];
+function validateLinks(filePath, content, fileSystem) {
+  const violations = [];
+  const lines = content.split(`
+`);
+  const fileDir = dirname(filePath);
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i];
+    const linkPattern = new RegExp(MARKDOWN_LINK_PATTERN.source, "g");
+    let match = linkPattern.exec(line);
+    while (match) {
+      const linkTarget = match[2];
+      if (!linkTarget.startsWith("http://") && !linkTarget.startsWith("https://") && !linkTarget.startsWith("#")) {
+        const targetPath = linkTarget.split("#")[0];
+        const resolvedPath = resolve(fileDir, targetPath);
+        if (!fileSystem.exists(resolvedPath)) {
+          violations.push({
+            file: filePath,
+            message: `Broken link: "${linkTarget}"`,
+            line: i + 1
+          });
+        }
+      }
+      match = linkPattern.exec(line);
+    }
+  }
+  return violations;
+}
+function validateSemanticLinks(filePath, content) {
+  const violations = [];
+  const lines = content.split(`
+`);
+  const fileDir = dirname(filePath);
+  let currentSection = null;
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith("## ")) {
+      currentSection = line;
+      continue;
+    }
+    const rule = SEMANTIC_RULES.find((r) => r.section === currentSection);
+    if (!rule)
+      continue;
+    const linkPattern = new RegExp(MARKDOWN_LINK_PATTERN.source, "g");
+    let match = linkPattern.exec(line);
+    while (match) {
+      const linkTarget = match[2];
+      if (linkTarget.startsWith("#")) {
+        violations.push({
+          file: filePath,
+          message: `Link in "${rule.section}" must point to a ${rule.description} file, not an anchor: "${linkTarget}"`,
+          line: i + 1
+        });
+        match = linkPattern.exec(line);
+        continue;
+      }
+      if (linkTarget.startsWith("http://") || linkTarget.startsWith("https://")) {
+        violations.push({
+          file: filePath,
+          message: `Link in "${rule.section}" must point to a ${rule.description} file, not an external URL: "${linkTarget}"`,
+          line: i + 1
+        });
+        match = linkPattern.exec(line);
+        continue;
+      }
+      const targetPath = linkTarget.split("#")[0];
+      const resolvedPath = resolve(fileDir, targetPath);
+      if (!resolvedPath.includes(rule.requiredPath)) {
+        violations.push({
+          file: filePath,
+          message: `Link in "${rule.section}" must point to a ${rule.description} file: "${linkTarget}"`,
+          line: i + 1
+        });
+      }
+      match = linkPattern.exec(line);
+    }
+  }
+  return violations;
+}
+function validatePrincipleHierarchyLinks(filePath, content) {
+  const violations = [];
+  const lines = content.split(`
+`);
+  const fileDir = dirname(filePath);
+  let currentSection = null;
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith("## ")) {
+      currentSection = line;
+      continue;
+    }
+    if (currentSection !== "## Parent Principle" && currentSection !== "## Sub-Principles") {
+      continue;
+    }
+    const linkPattern = new RegExp(MARKDOWN_LINK_PATTERN.source, "g");
+    let match = linkPattern.exec(line);
+    while (match) {
+      const linkTarget = match[2];
+      if (linkTarget.startsWith("#")) {
+        violations.push({
+          file: filePath,
+          message: `Link in "${currentSection}" must point to a principle file, not an anchor: "${linkTarget}"`,
+          line: i + 1
+        });
+        match = linkPattern.exec(line);
+        continue;
+      }
+      if (linkTarget.startsWith("http://") || linkTarget.startsWith("https://")) {
+        violations.push({
+          file: filePath,
+          message: `Link in "${currentSection}" must point to a principle file, not an external URL: "${linkTarget}"`,
+          line: i + 1
+        });
+        match = linkPattern.exec(line);
+        continue;
+      }
+      const targetPath = linkTarget.split("#")[0];
+      const resolvedPath = resolve(fileDir, targetPath);
+      if (!resolvedPath.includes("/.dust/principles/")) {
+        violations.push({
+          file: filePath,
+          message: `Link in "${currentSection}" must point to a principle file: "${linkTarget}"`,
+          line: i + 1
+        });
+      }
+      match = linkPattern.exec(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(filePath, content) {
+  const violations = [];
+  for (const heading of REQUIRED_PRINCIPLE_HEADINGS) {
+    if (!content.includes(heading)) {
+      violations.push({
+        file: filePath,
+        message: `Missing required heading: "${heading}"`
+      });
+    }
+  }
+  return violations;
+}
+function extractPrincipleRelationships(filePath, content) {
+  const lines = content.split(`
+`);
+  const fileDir = dirname2(filePath);
+  const parentPrinciples = [];
+  const subPrinciples = [];
+  let currentSection = null;
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      currentSection = line;
+      continue;
+    }
+    if (currentSection !== "## Parent Principle" && currentSection !== "## Sub-Principles") {
+      continue;
+    }
+    const linkPattern = new RegExp(MARKDOWN_LINK_PATTERN.source, "g");
+    let match = linkPattern.exec(line);
+    while (match) {
+      const linkTarget = match[2];
+      if (!linkTarget.startsWith("#") && !linkTarget.startsWith("http://") && !linkTarget.startsWith("https://")) {
+        const targetPath = linkTarget.split("#")[0];
+        const resolvedPath = resolve2(fileDir, targetPath);
+        if (resolvedPath.includes("/.dust/principles/")) {
+          if (currentSection === "## Parent Principle") {
+            parentPrinciples.push(resolvedPath);
+          } else {
+            subPrinciples.push(resolvedPath);
+          }
+        }
+      }
+      match = linkPattern.exec(line);
+    }
+  }
+  return { 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/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 {}
+      return Array.from(entries);
+    },
+    isDirectory(path) {
+      if (isDeleted(path))
+        return false;
+      return patchDirs.has(path) || base.isDirectory(path);
+    }
+  };
+}
+
+// lib/validation/index.ts
+async function validatePatch(fileSystem, 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);
+    }
+  }
+  const overlayFs = createOverlayFileSystem(fileSystem, absolutePatchFiles, deletedPaths);
+  const violations = [];
+  const contentDirs = ["principles", "facts", "ideas", "tasks"];
+  const patchDirs = new Set;
+  for (const relativePath of Object.keys(patch.files)) {
+    const dir = relativePath.split("/")[0];
+    if (contentDirs.includes(dir)) {
+      patchDirs.add(dir);
+    }
+  }
+  for (const dir of patchDirs) {
+    violations.push(...await validateContentDirectoryFiles(`${dustPath}/${dir}`, overlayFs));
+  }
+  for (const [relativePath, content] of Object.entries(patch.files)) {
+    if (content === null)
+      continue;
+    if (!relativePath.endsWith(".md"))
+      continue;
+    const filePath = `${dustPath}/${relativePath}`;
+    const dir = relativePath.split("/")[0];
+    violations.push(...validateLinks(filePath, content, overlayFs));
+    if (contentDirs.includes(dir)) {
+      const openingSentence = validateOpeningSentence(filePath, content);
+      if (openingSentence)
+        violations.push(openingSentence);
+      const openingSentenceLength = validateOpeningSentenceLength(filePath, content);
+      if (openingSentenceLength)
+        violations.push(openingSentenceLength);
+      const titleFilename = validateTitleFilenameMatch(filePath, content);
+      if (titleFilename)
+        violations.push(titleFilename);
+    }
+    if (dir === "ideas") {
+      violations.push(...validateIdeaOpenQuestions(filePath, content));
+    }
+    if (dir === "tasks") {
+      const filenameViolation = validateFilename(filePath);
+      if (filenameViolation)
+        violations.push(filenameViolation);
+      violations.push(...validateTaskHeadings(filePath, content));
+      violations.push(...validateSemanticLinks(filePath, content));
+      const imperativeViolation = validateImperativeOpeningSentence(filePath, content);
+      if (imperativeViolation)
+        violations.push(imperativeViolation);
+      const ideasPath = `${dustPath}/ideas`;
+      const ideaTransition = validateIdeaTransitionTitle(filePath, content, ideasPath, overlayFs);
+      if (ideaTransition)
+        violations.push(ideaTransition);
+      violations.push(...validateWorkflowTaskBodySection(filePath, content, ideasPath, overlayFs));
+    }
+    if (dir === "principles") {
+      violations.push(...validatePrincipleHierarchySections(filePath, content));
+      violations.push(...validatePrincipleHierarchyLinks(filePath, content));
+    }
+  }
+  const hasPrinciplePatches = Object.keys(patch.files).some((p) => p.startsWith("principles/"));
+  if (hasPrinciplePatches) {
+    const allRelationships = [];
+    const principlesPath = `${dustPath}/principles`;
+    try {
+      const existingFiles = await overlayFs.readdir(principlesPath);
+      for (const file of existingFiles) {
+        if (!file.endsWith(".md"))
+          continue;
+        const filePath = `${principlesPath}/${file}`;
+        const content = await overlayFs.readFile(filePath);
+        allRelationships.push(extractPrincipleRelationships(filePath, content));
+      }
+    } catch {}
+    violations.push(...validateBidirectionalLinks(allRelationships));
+    violations.push(...validateNoCycles(allRelationships));
+  }
+  return {
+    valid: violations.length === 0,
+    violations
+  };
+}
+export {
+  validatePatch
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joshski/dust",
-  "version": "0.1.73",
+  "version": "0.1.75",
   "description": "Flow state for AI coding agents",
   "type": "module",
   "bin": {
@@ -37,6 +37,10 @@
     "./biome": {
       "import": "./dist/biome.js",
       "types": "./dist/biome/index.d.ts"
+    },
+    "./validation": {
+      "import": "./dist/validation.js",
+      "types": "./dist/validation/index.d.ts"
     }
   },
   "files": [