@joshski/dust 0.1.59 → 0.1.60

package/dist/{ideas.d.ts → artifacts/ideas.d.ts}

@@ -1,4 +1,4 @@
-import type { FileSystem } from './cli/types';
+import type { ReadableFileSystem } from '../cli/types';
 export interface IdeaOption {
     name: string;
     description: string;
@@ -22,4 +22,4 @@ export declare function parseOpenQuestions(content: string): IdeaOpenQuestion[];
 /**
  * Parses an idea markdown file into a structured Idea object.
  */
-export declare function parseIdea(fileSystem: FileSystem, dustPath: string, slug: string): Promise<Idea>;
+export declare function parseIdea(fileSystem: ReadableFileSystem, dustPath: string, slug: string): Promise<Idea>;

package/dist/{workflow-tasks.d.ts → artifacts/workflow-tasks.d.ts}

@@ -1,4 +1,4 @@
-import type { FileSystem } from './cli/types';
+import type { FileSystem, ReadableFileSystem } from '../cli/types';
 export declare const IDEA_TRANSITION_PREFIXES: string[];
 export declare const CAPTURE_IDEA_PREFIX = "Add Idea: ";
 export declare const BUILD_IDEA_PREFIX = "Build Idea: ";
@@ -11,7 +11,7 @@ export interface ParsedCaptureIdeaTask {
     ideaDescription: string;
     buildItNow: boolean;
 }
-export declare function findAllCaptureIdeaTasks(fileSystem: FileSystem, dustPath: string): Promise<IdeaInProgress[]>;
+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
@@ -28,7 +28,7 @@ export interface WorkflowTaskMatch {
     ideaSlug: string;
     taskSlug: string;
 }
-export declare function findWorkflowTaskForIdea(fileSystem: FileSystem, dustPath: string, ideaSlug: string): Promise<WorkflowTaskMatch | null>;
+export declare function findWorkflowTaskForIdea(fileSystem: ReadableFileSystem, dustPath: string, ideaSlug: string): Promise<WorkflowTaskMatch | null>;
 export interface CreateIdeaTransitionTaskResult {
     filePath: string;
 }
@@ -49,4 +49,4 @@ export declare function createCaptureIdeaTask(fileSystem: FileSystem, dustPath:
     description: string;
     buildItNow?: boolean;
 }): Promise<CreateIdeaTransitionTaskResult>;
-export declare function parseCaptureIdeaTask(fileSystem: FileSystem, dustPath: string, taskSlug: string): Promise<ParsedCaptureIdeaTask | null>;
+export declare function parseCaptureIdeaTask(fileSystem: ReadableFileSystem, dustPath: string, taskSlug: string): Promise<ParsedCaptureIdeaTask | null>;

package/dist/artifacts.js

@@ -0,0 +1,599 @@
+// 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/artifacts/facts.ts
+async function parseFact(fileSystem, dustPath, slug) {
+  const factPath = `${dustPath}/facts/${slug}.md`;
+  if (!fileSystem.exists(factPath)) {
+    throw new Error(`Fact not found: "${slug}" (expected file at ${factPath})`);
+  }
+  const content = await fileSystem.readFile(factPath);
+  const title = extractTitle(content);
+  if (!title) {
+    throw new Error(`Fact file has no title: ${factPath}`);
+  }
+  return {
+    slug,
+    title,
+    content
+  };
+}
+
+// lib/artifacts/ideas.ts
+function parseOpenQuestions(content) {
+  const lines = content.split(`
+`);
+  const questions = [];
+  let inOpenQuestions = false;
+  let currentQuestion = null;
+  let currentOption = null;
+  let descriptionLines = [];
+  function flushOption() {
+    if (currentOption) {
+      currentOption.description = descriptionLines.join(`
+`).trim();
+      descriptionLines = [];
+      currentOption = null;
+    }
+  }
+  function flushQuestion() {
+    flushOption();
+    if (currentQuestion) {
+      questions.push(currentQuestion);
+      currentQuestion = null;
+    }
+  }
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      if (inOpenQuestions) {
+        flushQuestion();
+      }
+      inOpenQuestions = line.trimEnd() === "## Open Questions";
+      continue;
+    }
+    if (!inOpenQuestions)
+      continue;
+    if (line.startsWith("### ")) {
+      flushQuestion();
+      currentQuestion = {
+        question: line.slice(4).trim(),
+        options: []
+      };
+      continue;
+    }
+    if (line.startsWith("#### ")) {
+      flushOption();
+      currentOption = {
+        name: line.slice(5).trim(),
+        description: ""
+      };
+      if (currentQuestion) {
+        currentQuestion.options.push(currentOption);
+      }
+      continue;
+    }
+    if (currentOption) {
+      descriptionLines.push(line);
+    }
+  }
+  flushQuestion();
+  return questions;
+}
+async function parseIdea(fileSystem, dustPath, slug) {
+  const ideaPath = `${dustPath}/ideas/${slug}.md`;
+  if (!fileSystem.exists(ideaPath)) {
+    throw new Error(`Idea not found: "${slug}" (expected file at ${ideaPath})`);
+  }
+  const content = await fileSystem.readFile(ideaPath);
+  const title = extractTitle(content);
+  if (!title) {
+    throw new Error(`Idea file has no title: ${ideaPath}`);
+  }
+  const openingSentence = extractOpeningSentence(content);
+  const openQuestions = parseOpenQuestions(content);
+  return {
+    slug,
+    title,
+    openingSentence,
+    content,
+    openQuestions
+  };
+}
+
+// lib/artifacts/principles.ts
+function extractLinksFromSection(content, sectionHeading) {
+  const lines = content.split(`
+`);
+  const links = [];
+  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_PATTERN);
+    if (linkMatch) {
+      const target = linkMatch[2];
+      const slugMatch = target.match(/([^/]+)\.md$/);
+      if (slugMatch) {
+        links.push(slugMatch[1]);
+      }
+    }
+  }
+  return links;
+}
+function extractSingleLinkFromSection(content, sectionHeading) {
+  const links = extractLinksFromSection(content, sectionHeading);
+  return links.length === 1 ? links[0] : null;
+}
+async function parsePrinciple(fileSystem, dustPath, slug) {
+  const principlePath = `${dustPath}/principles/${slug}.md`;
+  if (!fileSystem.exists(principlePath)) {
+    throw new Error(`Principle not found: "${slug}" (expected file at ${principlePath})`);
+  }
+  const content = await fileSystem.readFile(principlePath);
+  const title = extractTitle(content);
+  if (!title) {
+    throw new Error(`Principle file has no title: ${principlePath}`);
+  }
+  const parentPrinciple = extractSingleLinkFromSection(content, "Parent Principle");
+  const subPrinciples = extractLinksFromSection(content, "Sub-Principles");
+  return {
+    slug,
+    title,
+    content,
+    parentPrinciple,
+    subPrinciples
+  };
+}
+
+// lib/artifacts/tasks.ts
+function extractLinksFromSection2(content, sectionHeading) {
+  const lines = content.split(`
+`);
+  const links = [];
+  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_PATTERN);
+    if (linkMatch) {
+      const target = linkMatch[2];
+      const slugMatch = target.match(/([^/]+)\.md$/);
+      if (slugMatch) {
+        links.push(slugMatch[1]);
+      }
+    }
+  }
+  return links;
+}
+function extractDefinitionOfDone(content) {
+  const lines = content.split(`
+`);
+  const items = [];
+  let inSection = false;
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      inSection = line.trimEnd() === "## Definition of Done";
+      continue;
+    }
+    if (!inSection)
+      continue;
+    if (line.startsWith("# "))
+      break;
+    const checklistMatch = line.match(/^-\s+\[[x\s]\]\s+(.+)$/i);
+    if (checklistMatch) {
+      items.push(checklistMatch[1].trim());
+    }
+  }
+  return items;
+}
+async function parseTask(fileSystem, dustPath, slug) {
+  const taskPath = `${dustPath}/tasks/${slug}.md`;
+  if (!fileSystem.exists(taskPath)) {
+    throw new Error(`Task not found: "${slug}" (expected file at ${taskPath})`);
+  }
+  const content = await fileSystem.readFile(taskPath);
+  const title = extractTitle(content);
+  if (!title) {
+    throw new Error(`Task file has no title: ${taskPath}`);
+  }
+  const principles = extractLinksFromSection2(content, "Principles");
+  const blockedBy = extractLinksFromSection2(content, "Blocked By");
+  const definitionOfDone = extractDefinitionOfDone(content);
+  return {
+    slug,
+    title,
+    content,
+    principles,
+    blockedBy,
+    definitionOfDone
+  };
+}
+
+// lib/artifacts/workflow-tasks.ts
+var CAPTURE_IDEA_PREFIX = "Add Idea: ";
+var BUILD_IDEA_PREFIX = "Build Idea: ";
+function titleToFilename(title) {
+  return `${title.toLowerCase().replace(/\./g, "-").replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "")}.md`;
+}
+var WORKFLOW_TASK_TYPES = [
+  { type: "refine", prefix: "Refine Idea: " },
+  { type: "decompose-idea", prefix: "Decompose Idea: " },
+  { type: "shelve", prefix: "Shelve Idea: " }
+];
+async function findWorkflowTaskForIdea(fileSystem, dustPath, ideaSlug) {
+  const ideaTitle = await readIdeaTitle(fileSystem, dustPath, ideaSlug);
+  for (const { type, prefix } of WORKFLOW_TASK_TYPES) {
+    const filename = titleToFilename(`${prefix}${ideaTitle}`);
+    const filePath = `${dustPath}/tasks/${filename}`;
+    if (fileSystem.exists(filePath)) {
+      const taskSlug = filename.replace(/\.md$/, "");
+      return { type, ideaSlug, taskSlug };
+    }
+  }
+  return null;
+}
+async function readIdeaTitle(fileSystem, dustPath, ideaSlug) {
+  const ideaPath = `${dustPath}/ideas/${ideaSlug}.md`;
+  if (!fileSystem.exists(ideaPath)) {
+    throw new Error(`Idea not found: "${ideaSlug}" (expected file at ${ideaPath})`);
+  }
+  const ideaContent = await fileSystem.readFile(ideaPath);
+  const ideaTitleMatch = ideaContent.match(/^#\s+(.+)$/m);
+  if (!ideaTitleMatch) {
+    throw new Error(`Idea file has no title: ${ideaPath}`);
+  }
+  return ideaTitleMatch[1].trim();
+}
+function renderResolvedQuestions(responses) {
+  const sections = responses.map((r) => `### ${r.question}
+
+**Decision:** ${r.chosenOption}`);
+  return `## Resolved Questions
+
+${sections.join(`
+
+`)}
+`;
+}
+function renderTask(title, openingSentence, definitionOfDone, options) {
+  const descriptionParagraph = options?.description !== undefined ? `
+${options.description}
+` : "";
+  const resolvedSection = options?.resolvedQuestions && options.resolvedQuestions.length > 0 ? `
+${renderResolvedQuestions(options.resolvedQuestions)}
+` : "";
+  return `# ${title}
+
+${openingSentence}
+${descriptionParagraph}${resolvedSection}
+## Principles
+
+(none)
+
+## Blocked By
+
+(none)
+
+## Definition of Done
+
+${definitionOfDone.map((item) => `- [ ] ${item}`).join(`
+`)}
+`;
+}
+async function createIdeaTask(fileSystem, dustPath, prefix, ideaSlug, openingSentenceTemplate, definitionOfDone, taskOptions) {
+  const ideaTitle = await readIdeaTitle(fileSystem, dustPath, ideaSlug);
+  const taskTitle = `${prefix}${ideaTitle}`;
+  const filename = titleToFilename(taskTitle);
+  const filePath = `${dustPath}/tasks/${filename}`;
+  const openingSentence = openingSentenceTemplate(ideaTitle);
+  const content = renderTask(taskTitle, openingSentence, definitionOfDone, taskOptions);
+  await fileSystem.writeFile(filePath, content);
+  return { filePath };
+}
+async function createRefineIdeaTask(fileSystem, dustPath, ideaSlug, description) {
+  return createIdeaTask(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.`, [
+    "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"
+  ], { description });
+}
+async function decomposeIdea(fileSystem, dustPath, options) {
+  return createIdeaTask(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).`, [
+    "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"
+  ], {
+    description: options.description,
+    resolvedQuestions: options.openQuestionResponses
+  });
+}
+async function createShelveIdeaTask(fileSystem, dustPath, ideaSlug, description) {
+  return createIdeaTask(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"], { description });
+}
+async function createCaptureIdeaTask(fileSystem, dustPath, options) {
+  const { title, description, buildItNow } = options;
+  if (!title || !title.trim()) {
+    throw new Error("title is required and must not be whitespace-only");
+  }
+  if (!description || !description.trim()) {
+    throw new Error("description is required and must not be whitespace-only");
+  }
+  if (buildItNow) {
+    const taskTitle2 = `${BUILD_IDEA_PREFIX}${title}`;
+    const filename2 = titleToFilename(taskTitle2);
+    const filePath2 = `${dustPath}/tasks/${filename2}`;
+    const content2 = `# ${taskTitle2}
+
+Research this idea thoroughly, then create one or more narrowly-scoped task files in \`.dust/tasks/\`. Review \`.dust/principles/\` and \`.dust/facts/\` for relevant context. Each task should deliver a thin but complete vertical slice of working software.
+
+## Idea Description
+
+${description}
+
+## Principles
+
+(none)
+
+## Blocked By
+
+(none)
+
+## Definition of Done
+
+- [ ] One or more new tasks are created in \`.dust/tasks/\`
+- [ ] Tasks link to relevant principles from \`.dust/principles/\`
+- [ ] Tasks are narrowly scoped vertical slices
+`;
+    await fileSystem.writeFile(filePath2, content2);
+    return { filePath: filePath2 };
+  }
+  const taskTitle = `${CAPTURE_IDEA_PREFIX}${title}`;
+  const filename = titleToFilename(taskTitle);
+  const filePath = `${dustPath}/tasks/${filename}`;
+  const ideaFilename = titleToFilename(title);
+  const ideaPath = `.dust/ideas/${ideaFilename}`;
+  const content = `# ${taskTitle}
+
+Research this idea thoroughly, then create an idea file at \`${ideaPath}\`. 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.
+
+## Idea Description
+
+${description}
+
+## Principles
+
+(none)
+
+## Blocked By
+
+(none)
+
+## Definition of Done
+
+- [ ] Idea file exists at ${ideaPath}
+- [ ] Idea file has an H1 title matching "${title}"
+- [ ] Idea includes relevant context from codebase exploration
+- [ ] Open questions are added for any ambiguous or underspecified aspects
+- [ ] Open questions follow the required heading format and focus on high-value decisions
+`;
+  await fileSystem.writeFile(filePath, content);
+  return { filePath };
+}
+async function parseCaptureIdeaTask(fileSystem, dustPath, taskSlug) {
+  const filePath = `${dustPath}/tasks/${taskSlug}.md`;
+  if (!fileSystem.exists(filePath)) {
+    return null;
+  }
+  const content = await fileSystem.readFile(filePath);
+  const titleMatch = content.match(/^#\s+(.+)$/m);
+  if (!titleMatch) {
+    return null;
+  }
+  const title = titleMatch[1].trim();
+  let ideaTitle;
+  let buildItNow;
+  if (title.startsWith(BUILD_IDEA_PREFIX)) {
+    ideaTitle = title.slice(BUILD_IDEA_PREFIX.length);
+    buildItNow = true;
+  } else if (title.startsWith(CAPTURE_IDEA_PREFIX)) {
+    ideaTitle = title.slice(CAPTURE_IDEA_PREFIX.length);
+    buildItNow = false;
+  } else {
+    return null;
+  }
+  const descriptionMatch = content.match(/^## Idea Description\n\n([\s\S]*?)\n\n## /m);
+  if (!descriptionMatch) {
+    return null;
+  }
+  const ideaDescription = descriptionMatch[1];
+  return { ideaTitle, ideaDescription, buildItNow };
+}
+
+// lib/artifacts/index.ts
+function buildArtifactsRepository(fileSystem, dustPath) {
+  return {
+    async parseIdea(options) {
+      return parseIdea(fileSystem, dustPath, options.slug);
+    },
+    async listIdeas() {
+      const ideasPath = `${dustPath}/ideas`;
+      if (!fileSystem.exists(ideasPath)) {
+        return [];
+      }
+      const files = await fileSystem.readdir(ideasPath);
+      return files.filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, "")).sort();
+    },
+    async parsePrinciple(options) {
+      return parsePrinciple(fileSystem, dustPath, options.slug);
+    },
+    async listPrinciples() {
+      const principlesPath = `${dustPath}/principles`;
+      if (!fileSystem.exists(principlesPath)) {
+        return [];
+      }
+      const files = await fileSystem.readdir(principlesPath);
+      return files.filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, "")).sort();
+    },
+    async parseFact(options) {
+      return parseFact(fileSystem, dustPath, options.slug);
+    },
+    async listFacts() {
+      const factsPath = `${dustPath}/facts`;
+      if (!fileSystem.exists(factsPath)) {
+        return [];
+      }
+      const files = await fileSystem.readdir(factsPath);
+      return files.filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, "")).sort();
+    },
+    async parseTask(options) {
+      return parseTask(fileSystem, dustPath, options.slug);
+    },
+    async listTasks() {
+      const tasksPath = `${dustPath}/tasks`;
+      if (!fileSystem.exists(tasksPath)) {
+        return [];
+      }
+      const files = await fileSystem.readdir(tasksPath);
+      return files.filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, "")).sort();
+    },
+    async createRefineIdeaTask(options) {
+      return createRefineIdeaTask(fileSystem, dustPath, options.ideaSlug, options.description);
+    },
+    async createDecomposeIdeaTask(options) {
+      return decomposeIdea(fileSystem, dustPath, options);
+    },
+    async createShelveIdeaTask(options) {
+      return createShelveIdeaTask(fileSystem, dustPath, options.ideaSlug, options.description);
+    },
+    async createCaptureIdeaTask(options) {
+      return createCaptureIdeaTask(fileSystem, dustPath, options);
+    },
+    async findWorkflowTaskForIdea(options) {
+      return findWorkflowTaskForIdea(fileSystem, dustPath, options.ideaSlug);
+    },
+    async parseCaptureIdeaTask(options) {
+      return parseCaptureIdeaTask(fileSystem, dustPath, options.taskSlug);
+    }
+  };
+}
+function buildReadOnlyArtifactsRepository(fileSystem, dustPath) {
+  return {
+    async parseIdea(options) {
+      return parseIdea(fileSystem, dustPath, options.slug);
+    },
+    async listIdeas() {
+      const ideasPath = `${dustPath}/ideas`;
+      if (!fileSystem.exists(ideasPath)) {
+        return [];
+      }
+      const files = await fileSystem.readdir(ideasPath);
+      return files.filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, "")).sort();
+    },
+    async parsePrinciple(options) {
+      return parsePrinciple(fileSystem, dustPath, options.slug);
+    },
+    async listPrinciples() {
+      const principlesPath = `${dustPath}/principles`;
+      if (!fileSystem.exists(principlesPath)) {
+        return [];
+      }
+      const files = await fileSystem.readdir(principlesPath);
+      return files.filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, "")).sort();
+    },
+    async parseFact(options) {
+      return parseFact(fileSystem, dustPath, options.slug);
+    },
+    async listFacts() {
+      const factsPath = `${dustPath}/facts`;
+      if (!fileSystem.exists(factsPath)) {
+        return [];
+      }
+      const files = await fileSystem.readdir(factsPath);
+      return files.filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, "")).sort();
+    },
+    async parseTask(options) {
+      return parseTask(fileSystem, dustPath, options.slug);
+    },
+    async listTasks() {
+      const tasksPath = `${dustPath}/tasks`;
+      if (!fileSystem.exists(tasksPath)) {
+        return [];
+      }
+      const files = await fileSystem.readdir(tasksPath);
+      return files.filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, "")).sort();
+    },
+    async findWorkflowTaskForIdea(options) {
+      return findWorkflowTaskForIdea(fileSystem, dustPath, options.ideaSlug);
+    },
+    async parseCaptureIdeaTask(options) {
+      return parseCaptureIdeaTask(fileSystem, dustPath, options.taskSlug);
+    }
+  };
+}
+export {
+  parseOpenQuestions,
+  buildReadOnlyArtifactsRepository,
+  buildArtifactsRepository
+};

package/dist/cli/types.d.ts

@@ -13,16 +13,18 @@ export interface CommandResult {
 export interface WriteOptions {
     flag?: 'w' | 'wx';
 }
-export interface FileSystem {
+export interface ReadableFileSystem {
     exists: (path: string) => boolean;
     readFile: (path: string) => Promise<string>;
+    readdir: (path: string) => Promise<string[]>;
+    isDirectory: (path: string) => boolean;
+}
+export interface FileSystem extends ReadableFileSystem {
     writeFile: (path: string, content: string, options?: WriteOptions) => Promise<void>;
     mkdir: (path: string, options?: {
         recursive?: boolean;
     }) => Promise<void>;
-    readdir: (path: string) => Promise<string[]>;
     chmod: (path: string, mode: number) => Promise<void>;
-    isDirectory: (path: string) => boolean;
     getFileCreationTime: (path: string) => number;
     rename: (oldPath: string, newPath: string) => Promise<void>;
 }

package/dist/dust.js

@@ -1823,7 +1823,7 @@ import os from "node:os";
 import { dirname as dirname2, join as join7 } from "node:path";
 import { fileURLToPath } from "node:url";
 
-// lib/workflow-tasks.ts
+// lib/artifacts/workflow-tasks.ts
 var IDEA_TRANSITION_PREFIXES = [
   "Refine Idea: ",
   "Decompose Idea: ",
@@ -4917,7 +4917,7 @@ function newIdeaInstructions(vars) {
     4. Write a brief description of the potential change or improvement
     5. If the idea has open questions, add an \`## Open Questions\` section (see below)
     6. Run \`${vars.bin} lint\` to catch any issues with the idea file format
-    7. Create a single atomic commit with a message in the format "Add idea: <title>"
+    7. Create a single atomic commit with a message in the format "Create task: Add idea: <title>"
     8. Push your commit to the remote repository
 
     ### Open Questions section
@@ -4980,7 +4980,7 @@ function newPrincipleInstructions(vars) {
        - Why it matters for the project
        - How to evaluate whether work supports this principle
     5. Run \`${vars.bin} lint\` to catch any formatting issues
-    6. Create a single atomic commit with a message in the format "Add principle: <title>"
+    6. Create a single atomic commit with a message in the format "Create task: Add principle: <title>"
     7. Push your commit to the remote repository
 
     Principles should be:
@@ -5027,7 +5027,7 @@ function newTaskInstructions(vars) {
   steps.push("8. Add a `## Blocked By` section listing any tasks that must complete first, or `(none)` if there are no blockers");
   steps.push("9. Add a `## Definition of Done` section with a checklist of completion criteria using `- [ ]` for each item");
   steps.push(`10. Run \`${vars.bin} lint\` to catch any issues with the task format`);
-  steps.push('11. Create a single atomic commit with a message in the format "Add task: <title>" that includes:');
+  steps.push('11. Create a single atomic commit with a message in the format "Create task: Add task: <title>" that includes:');
   steps.push("    - The new task file");
   steps.push("    - Deletion of the idea file that spawned this task (if remaining scope exists, create new ideas for it)");
   if (vars.isClaudeCodeWeb) {

package/dist/types.d.ts

@@ -5,5 +5,5 @@
  * the event protocol, workflow tasks, and idea structures.
  */
 export type { AgentSessionEvent, EventMessage } from './agent-events';
-export type { Idea, IdeaOpenQuestion, IdeaOption } from './ideas';
-export type { CreateIdeaTransitionTaskResult, DecomposeIdeaOptions, IdeaInProgress, OpenQuestionResponse, ParsedCaptureIdeaTask, WorkflowTaskMatch, WorkflowTaskType, } from './workflow-tasks';
+export type { Idea, IdeaOpenQuestion, IdeaOption } from './artifacts/ideas';
+export type { CreateIdeaTransitionTaskResult, DecomposeIdeaOptions, IdeaInProgress, OpenQuestionResponse, ParsedCaptureIdeaTask, WorkflowTaskMatch, WorkflowTaskType, } from './artifacts/workflow-tasks';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joshski/dust",
-  "version": "0.1.59",
+  "version": "0.1.60",
   "description": "Flow state for AI coding agents",
   "type": "module",
   "bin": {
@@ -10,10 +10,6 @@
     "./types": {
       "types": "./dist/types.d.ts"
     },
-    "./workflow-tasks": {
-      "import": "./dist/workflow-tasks.js",
-      "types": "./dist/workflow-tasks.d.ts"
-    },
     "./logging": {
       "import": "./dist/logging.js",
       "types": "./dist/logging/index.d.ts"
@@ -22,9 +18,9 @@
       "import": "./dist/agents.js",
       "types": "./dist/agents/detection.d.ts"
     },
-    "./ideas": {
-      "import": "./dist/ideas.js",
-      "types": "./dist/ideas.d.ts"
+    "./artifacts": {
+      "import": "./dist/artifacts.js",
+      "types": "./dist/artifacts.d.ts"
     },
     "./istanbul/minimal-reporter": "./lib/istanbul/minimal-reporter.cjs"
   },
@@ -46,7 +42,7 @@
   "author": "joshski",
   "license": "MIT",
   "scripts": {
-    "build": "bun build lib/cli/run.ts --target node --outfile dist/dust.js && printf '%s\\n%s' '#!/usr/bin/env node' \"$(cat dist/dust.js)\" > dist/dust.js && bun build lib/workflow-tasks.ts --target node --outfile dist/workflow-tasks.js && bun build lib/logging/index.ts --target node --outfile dist/logging.js && bun build lib/agents/detection.ts --target node --outfile dist/agents.js && bun build lib/ideas.ts --target node --outfile dist/ideas.js && bunx tsc --project tsconfig.build.json",
+    "build": "bun build lib/cli/run.ts --target node --outfile dist/dust.js && printf '%s\\n%s' '#!/usr/bin/env node' \"$(cat dist/dust.js)\" > dist/dust.js && bun build lib/logging/index.ts --target node --outfile dist/logging.js && bun build lib/agents/detection.ts --target node --outfile dist/agents.js && bun build lib/artifacts/index.ts --target node --outfile dist/artifacts.js && bunx tsc --project tsconfig.build.json",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "eval": "bun run ./evals/run.ts"

package/dist/ideas.js

@@ -1,135 +0,0 @@
-// lib/markdown/markdown-utilities.ts
-function extractTitle(content) {
-  const match = content.match(/^#\s+(.+)$/m);
-  return match ? match[1].trim() : null;
-}
-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/ideas.ts
-function parseOpenQuestions(content) {
-  const lines = content.split(`
-`);
-  const questions = [];
-  let inOpenQuestions = false;
-  let currentQuestion = null;
-  let currentOption = null;
-  let descriptionLines = [];
-  function flushOption() {
-    if (currentOption) {
-      currentOption.description = descriptionLines.join(`
-`).trim();
-      descriptionLines = [];
-      currentOption = null;
-    }
-  }
-  function flushQuestion() {
-    flushOption();
-    if (currentQuestion) {
-      questions.push(currentQuestion);
-      currentQuestion = null;
-    }
-  }
-  for (const line of lines) {
-    if (line.startsWith("## ")) {
-      if (inOpenQuestions) {
-        flushQuestion();
-      }
-      inOpenQuestions = line.trimEnd() === "## Open Questions";
-      continue;
-    }
-    if (!inOpenQuestions)
-      continue;
-    if (line.startsWith("### ")) {
-      flushQuestion();
-      currentQuestion = {
-        question: line.slice(4).trim(),
-        options: []
-      };
-      continue;
-    }
-    if (line.startsWith("#### ")) {
-      flushOption();
-      currentOption = {
-        name: line.slice(5).trim(),
-        description: ""
-      };
-      if (currentQuestion) {
-        currentQuestion.options.push(currentOption);
-      }
-      continue;
-    }
-    if (currentOption) {
-      descriptionLines.push(line);
-    }
-  }
-  flushQuestion();
-  return questions;
-}
-async function parseIdea(fileSystem, dustPath, slug) {
-  const ideaPath = `${dustPath}/ideas/${slug}.md`;
-  if (!fileSystem.exists(ideaPath)) {
-    throw new Error(`Idea not found: "${slug}" (expected file at ${ideaPath})`);
-  }
-  const content = await fileSystem.readFile(ideaPath);
-  const title = extractTitle(content);
-  if (!title) {
-    throw new Error(`Idea file has no title: ${ideaPath}`);
-  }
-  const openingSentence = extractOpeningSentence(content);
-  const openQuestions = parseOpenQuestions(content);
-  return {
-    slug,
-    title,
-    openingSentence,
-    content,
-    openQuestions
-  };
-}
-export {
-  parseOpenQuestions,
-  parseIdea
-};

package/dist/workflow-tasks.js

@@ -1,244 +0,0 @@
-// lib/workflow-tasks.ts
-var IDEA_TRANSITION_PREFIXES = [
-  "Refine Idea: ",
-  "Decompose Idea: ",
-  "Shelve Idea: "
-];
-var CAPTURE_IDEA_PREFIX = "Add Idea: ";
-var BUILD_IDEA_PREFIX = "Build 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(BUILD_IDEA_PREFIX)) {
-      results.push({
-        taskSlug: file.replace(/\.md$/, ""),
-        ideaTitle: title.slice(BUILD_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`;
-}
-var WORKFLOW_TASK_TYPES = [
-  { type: "refine", prefix: "Refine Idea: " },
-  { type: "decompose-idea", prefix: "Decompose Idea: " },
-  { type: "shelve", prefix: "Shelve Idea: " }
-];
-async function findWorkflowTaskForIdea(fileSystem, dustPath, ideaSlug) {
-  const ideaTitle = await readIdeaTitle(fileSystem, dustPath, ideaSlug);
-  for (const { type, prefix } of WORKFLOW_TASK_TYPES) {
-    const filename = titleToFilename(`${prefix}${ideaTitle}`);
-    const filePath = `${dustPath}/tasks/${filename}`;
-    if (fileSystem.exists(filePath)) {
-      const taskSlug = filename.replace(/\.md$/, "");
-      return { type, ideaSlug, taskSlug };
-    }
-  }
-  return null;
-}
-async function readIdeaTitle(fileSystem, dustPath, ideaSlug) {
-  const ideaPath = `${dustPath}/ideas/${ideaSlug}.md`;
-  if (!fileSystem.exists(ideaPath)) {
-    throw new Error(`Idea not found: "${ideaSlug}" (expected file at ${ideaPath})`);
-  }
-  const ideaContent = await fileSystem.readFile(ideaPath);
-  const ideaTitleMatch = ideaContent.match(/^#\s+(.+)$/m);
-  if (!ideaTitleMatch) {
-    throw new Error(`Idea file has no title: ${ideaPath}`);
-  }
-  return ideaTitleMatch[1].trim();
-}
-function renderResolvedQuestions(responses) {
-  const sections = responses.map((r) => `### ${r.question}
-
-**Decision:** ${r.chosenOption}`);
-  return `## Resolved Questions
-
-${sections.join(`
-
-`)}
-`;
-}
-function renderTask(title, openingSentence, definitionOfDone, options) {
-  const descriptionParagraph = options?.description !== undefined ? `
-${options.description}
-` : "";
-  const resolvedSection = options?.resolvedQuestions && options.resolvedQuestions.length > 0 ? `
-${renderResolvedQuestions(options.resolvedQuestions)}
-` : "";
-  return `# ${title}
-
-${openingSentence}
-${descriptionParagraph}${resolvedSection}
-## Principles
-
-(none)
-
-## Blocked By
-
-(none)
-
-## Definition of Done
-
-${definitionOfDone.map((item) => `- [ ] ${item}`).join(`
-`)}
-`;
-}
-async function createIdeaTask(fileSystem, dustPath, prefix, ideaSlug, openingSentenceTemplate, definitionOfDone, taskOptions) {
-  const ideaTitle = await readIdeaTitle(fileSystem, dustPath, ideaSlug);
-  const taskTitle = `${prefix}${ideaTitle}`;
-  const filename = titleToFilename(taskTitle);
-  const filePath = `${dustPath}/tasks/${filename}`;
-  const openingSentence = openingSentenceTemplate(ideaTitle);
-  const content = renderTask(taskTitle, openingSentence, definitionOfDone, taskOptions);
-  await fileSystem.writeFile(filePath, content);
-  return { filePath };
-}
-async function createRefineIdeaTask(fileSystem, dustPath, ideaSlug, description) {
-  return createIdeaTask(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.`, [
-    "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"
-  ], { description });
-}
-async function decomposeIdea(fileSystem, dustPath, options) {
-  return createIdeaTask(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).`, [
-    "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"
-  ], {
-    description: options.description,
-    resolvedQuestions: options.openQuestionResponses
-  });
-}
-async function createShelveIdeaTask(fileSystem, dustPath, ideaSlug, description) {
-  return createIdeaTask(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"], { description });
-}
-async function createCaptureIdeaTask(fileSystem, dustPath, options) {
-  const { title, description, buildItNow } = options;
-  if (!title || !title.trim()) {
-    throw new Error("title is required and must not be whitespace-only");
-  }
-  if (!description || !description.trim()) {
-    throw new Error("description is required and must not be whitespace-only");
-  }
-  if (buildItNow) {
-    const taskTitle2 = `${BUILD_IDEA_PREFIX}${title}`;
-    const filename2 = titleToFilename(taskTitle2);
-    const filePath2 = `${dustPath}/tasks/${filename2}`;
-    const content2 = `# ${taskTitle2}
-
-Research this idea thoroughly, then create one or more narrowly-scoped task files in \`.dust/tasks/\`. Review \`.dust/principles/\` and \`.dust/facts/\` for relevant context. Each task should deliver a thin but complete vertical slice of working software.
-
-## Idea Description
-
-${description}
-
-## Principles
-
-(none)
-
-## Blocked By
-
-(none)
-
-## Definition of Done
-
-- [ ] One or more new tasks are created in \`.dust/tasks/\`
-- [ ] Tasks link to relevant principles from \`.dust/principles/\`
-- [ ] Tasks are narrowly scoped vertical slices
-`;
-    await fileSystem.writeFile(filePath2, content2);
-    return { filePath: filePath2 };
-  }
-  const taskTitle = `${CAPTURE_IDEA_PREFIX}${title}`;
-  const filename = titleToFilename(taskTitle);
-  const filePath = `${dustPath}/tasks/${filename}`;
-  const ideaFilename = titleToFilename(title);
-  const ideaPath = `.dust/ideas/${ideaFilename}`;
-  const content = `# ${taskTitle}
-
-Research this idea thoroughly, then create an idea file at \`${ideaPath}\`. 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.
-
-## Idea Description
-
-${description}
-
-## Principles
-
-(none)
-
-## Blocked By
-
-(none)
-
-## Definition of Done
-
-- [ ] Idea file exists at ${ideaPath}
-- [ ] Idea file has an H1 title matching "${title}"
-- [ ] Idea includes relevant context from codebase exploration
-- [ ] Open questions are added for any ambiguous or underspecified aspects
-- [ ] Open questions follow the required heading format and focus on high-value decisions
-`;
-  await fileSystem.writeFile(filePath, content);
-  return { filePath };
-}
-async function parseCaptureIdeaTask(fileSystem, dustPath, taskSlug) {
-  const filePath = `${dustPath}/tasks/${taskSlug}.md`;
-  if (!fileSystem.exists(filePath)) {
-    return null;
-  }
-  const content = await fileSystem.readFile(filePath);
-  const titleMatch = content.match(/^#\s+(.+)$/m);
-  if (!titleMatch) {
-    return null;
-  }
-  const title = titleMatch[1].trim();
-  let ideaTitle;
-  let buildItNow;
-  if (title.startsWith(BUILD_IDEA_PREFIX)) {
-    ideaTitle = title.slice(BUILD_IDEA_PREFIX.length);
-    buildItNow = true;
-  } else if (title.startsWith(CAPTURE_IDEA_PREFIX)) {
-    ideaTitle = title.slice(CAPTURE_IDEA_PREFIX.length);
-    buildItNow = false;
-  } else {
-    return null;
-  }
-  const descriptionMatch = content.match(/^## Idea Description\n\n([\s\S]*?)\n\n## /m);
-  if (!descriptionMatch) {
-    return null;
-  }
-  const ideaDescription = descriptionMatch[1];
-  return { ideaTitle, ideaDescription, buildItNow };
-}
-export {
-  titleToFilename,
-  parseCaptureIdeaTask,
-  findWorkflowTaskForIdea,
-  findAllCaptureIdeaTasks,
-  decomposeIdea,
-  createShelveIdeaTask,
-  createRefineIdeaTask,
-  createCaptureIdeaTask,
-  IDEA_TRANSITION_PREFIXES,
-  CAPTURE_IDEA_PREFIX,
-  BUILD_IDEA_PREFIX
-};