@joshski/dust 0.1.102 → 0.1.104

package/dist/filesystem/types.d.ts

@@ -4,12 +4,16 @@
 export interface WriteOptions {
     flag?: 'w' | 'wx';
 }
-export interface ReadableFileSystem {
+export interface FileReader {
     exists: (path: string) => boolean;
     readFile: (path: string) => Promise<string>;
+}
+export interface DirectoryReader {
     readdir: (path: string) => Promise<string[]>;
     isDirectory: (path: string) => boolean;
 }
+export interface ReadableFileSystem extends FileReader, DirectoryReader {
+}
 export interface FileSystem extends ReadableFileSystem {
     writeFile: (path: string, content: string, options?: WriteOptions) => Promise<void>;
     mkdir: (path: string, options?: {

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

@@ -0,0 +1,15 @@
+/**
+ * Audit file validation for .dust/config/audits/ markdown files.
+ *
+ * Custom audits must follow the same structure as stock audits:
+ * - Opening description after H1 title
+ * - ## Scope section
+ * - ## Blocked By section
+ * - ## Definition of Done section
+ */
+import type { ParsedArtifact } from '../../artifacts/parsed-artifact';
+import type { Violation } from './types';
+/**
+ * Validates that an audit file contains all required section headings.
+ */
+export declare function validateAuditHeadings(artifact: ParsedArtifact): Violation[];

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

@@ -7,3 +7,4 @@ export declare function validateOpeningSentence(artifact: ParsedArtifact): Viola
 export declare function validateOpeningSentenceLength(artifact: ParsedArtifact): Violation | null;
 export declare function validateImperativeOpeningSentence(artifact: ParsedArtifact): Violation | null;
 export declare function validateTaskHeadings(artifact: ParsedArtifact): Violation[];
+export declare function validateTaskType(artifact: ParsedArtifact): Violation | null;

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

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

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

@@ -2,8 +2,8 @@
  * Idea file validation for .dust markdown files
  */
 import type { ParsedArtifact } from '../../artifacts/parsed-artifact';
-import type { ReadableFileSystem } from '../../filesystem/types';
+import type { FileReader } from '../../filesystem/types';
 import type { Violation } from './types';
 export declare function validateIdeaOpenQuestions(artifact: ParsedArtifact): Violation[];
-export declare function validateIdeaTransitionTitle(artifact: ParsedArtifact, ideasPath: string, fileSystem: ReadableFileSystem): Violation | null;
-export declare function validateWorkflowTaskBodySection(artifact: ParsedArtifact, ideasPath: string, fileSystem: ReadableFileSystem): Violation[];
+export declare function validateIdeaTransitionTitle(_artifact: ParsedArtifact, _ideasPath: string, _fileSystem: FileReader): Violation | null;
+export declare function validateWorkflowTaskBodySection(_artifact: ParsedArtifact, _ideasPath: string, _fileSystem: FileReader): Violation[];

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

@@ -2,8 +2,8 @@
  * Link validation for .dust markdown files
  */
 import type { ParsedArtifact } from '../../artifacts/parsed-artifact';
-import type { ReadableFileSystem } from '../../filesystem/types';
+import type { FileReader } from '../../filesystem/types';
 import type { Violation } from './types';
-export declare function validateLinks(artifact: ParsedArtifact, fileSystem: ReadableFileSystem): Violation[];
+export declare function validateLinks(artifact: ParsedArtifact, fileSystem: FileReader): Violation[];
 export declare function validateSemanticLinks(artifact: ParsedArtifact): Violation[];
 export declare function validatePrincipleHierarchyLinks(artifact: ParsedArtifact): Violation[];

package/dist/loop/iteration.d.ts

@@ -1,6 +1,5 @@
 import { spawn as nodeSpawn } from 'node:child_process';
-import { run as claudeRun } from '../claude/run';
-import type { DockerSpawnConfig } from '../claude/types';
+import type { BoundRunFn, DockerSpawnConfig } from '../claude/types';
 import type { DockerDependencies } from '../docker/docker-agent';
 import { type SessionConfig } from '../env-config';
 import { type ShellRunner } from '../cli/process-runner';
@@ -11,7 +10,7 @@ import type { PostEventFn, SendAgentEventFn } from './wire-events';
 export declare const DUST_QUICK_REFERENCE = "## Dust Quick Reference\n\nDust stores project context in `.dust/` as markdown artifacts. Use these commands to explore:\n\n- `dust ideas` \u2014 list ideas for future work\n- `dust principles` \u2014 show guiding values and design constraints\n- `dust facts` \u2014 show current state documentation\n- `dust help` \u2014 see all available commands\n\nUse dust commands instead of manually searching `.dust/` directories.";
 export interface LoopDependencies {
     spawn: typeof nodeSpawn;
-    run: typeof claudeRun;
+    run: BoundRunFn;
     sleep: (ms: number) => Promise<void>;
     postEvent: PostEventFn;
     session: SessionConfig;
@@ -39,6 +38,8 @@ export interface IterationOptions {
     proxyPort?: number;
     /** Branch name when working on a non-default branch */
     branch?: string;
+    /** Trace ID for correlating events across processes */
+    traceId?: string;
 }
 export declare function findAvailableTasks(dependencies: CommandDependencies): Promise<{
     tasks: UnblockedTask[];

package/dist/patch/index.d.ts

@@ -42,6 +42,19 @@ export interface BuildArtifactPatchResult {
 interface ValidatePatchOptions {
     cwd?: string;
 }
+/**
+ * Parses artifact type and slug from a file path.
+ * E.g., 'facts/my-fact.md' → { type: 'fact', slug: 'my-fact' }
+ */
+export declare function parseArtifactPath(path: string): {
+    type: ArtifactType;
+    slug: string;
+} | null;
+/**
+ * Builds preview objects from patch files.
+ * For create vs update determination, checks filesystem existence.
+ */
+export declare function buildPreviews(fileSystem: ReadableFileSystem, dustPath: string, files: Record<string, string | null>): Promise<ArtifactPreview[]>;
 /**
  * Builds an artifact patch from structured input objects.
  *

package/dist/patch.js

@@ -139,12 +139,6 @@ function extractFirstSentence(paragraph) {
 }
 
 // lib/artifacts/workflow-tasks.ts
-var IDEA_TRANSITION_PREFIXES = [
-  "Refine Idea: ",
-  "Decompose Idea: ",
-  "Shelve Idea: ",
-  "Expedite Idea: "
-];
 function titleToFilename(title) {
   return `${title.toLowerCase().replace(/\./g, "-").replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "")}.md`;
 }
@@ -225,8 +219,31 @@ function createOverlayFileSystem(base, patchFiles, deletedPaths = new Set) {
   };
 }
 
+// lib/lint/validators/audit-validator.ts
+var REQUIRED_AUDIT_HEADINGS = ["Scope", "Blocked By", "Definition of Done"];
+function validateAuditHeadings(artifact) {
+  const violations = [];
+  const sectionHeadings = new Set(artifact.sections.map((s) => s.heading));
+  for (const heading of REQUIRED_AUDIT_HEADINGS) {
+    if (!sectionHeadings.has(heading)) {
+      violations.push({
+        file: artifact.filePath,
+        message: `Missing required heading: "## ${heading}"`
+      });
+    }
+  }
+  return violations;
+}
+
 // lib/lint/validators/content-validator.ts
-var REQUIRED_TASK_HEADINGS = ["Blocked By", "Definition of Done"];
+var REQUIRED_TASK_HEADINGS = ["Task Type", "Blocked By", "Definition of Done"];
+var ALLOWED_TASK_TYPES = new Set([
+  "implement",
+  "capture",
+  "refine",
+  "decompose",
+  "shelve"
+]);
 var MAX_OPENING_SENTENCE_LENGTH = 150;
 var NON_IMPERATIVE_STARTERS = new Set([
   "the",
@@ -296,6 +313,32 @@ function validateTaskHeadings(artifact) {
   }
   return violations;
 }
+function validateTaskType(artifact) {
+  const taskTypeSection = artifact.sections.find((s) => s.heading === "Task Type");
+  if (!taskTypeSection) {
+    return null;
+  }
+  const lines = artifact.rawContent.split(`
+`);
+  const sectionLines = lines.slice(taskTypeSection.startLine, taskTypeSection.endLine + 1);
+  const content = sectionLines.join(`
+`).trim();
+  if (!content) {
+    return {
+      file: artifact.filePath,
+      line: taskTypeSection.startLine,
+      message: "Task Type section must contain one of: implement, capture, refine, decompose, shelve"
+    };
+  }
+  if (!ALLOWED_TASK_TYPES.has(content)) {
+    return {
+      file: artifact.filePath,
+      line: taskTypeSection.startLine,
+      message: `Invalid task type "${content}". Must be one of: implement, capture, refine, decompose, shelve`
+    };
+  }
+  return null;
+}
 
 // lib/lint/validators/directory-validator.ts
 var EXPECTED_DIRECTORIES = [...ARTIFACT_TYPES, "config"];
@@ -367,12 +410,6 @@ function validateTitleFilenameMatch(artifact) {
 }
 
 // lib/lint/validators/idea-validator.ts
-var WORKFLOW_PREFIX_TO_SECTION = {
-  "Refine Idea: ": "Refines Idea",
-  "Decompose Idea: ": "Decomposes Idea",
-  "Shelve Idea: ": "Shelves Idea",
-  "Expedite Idea: ": "Expedites Idea"
-};
 function validateH2Heading(filePath, line, lineNumber, inOpenQuestions, currentQuestionLine) {
   const violations = [];
   if (inOpenQuestions && currentQuestionLine !== null) {
@@ -479,96 +516,6 @@ function validateIdeaOpenQuestions(artifact) {
   }
   return violations;
 }
-function validateIdeaTransitionTitle(artifact, ideasPath, fileSystem) {
-  const title = artifact.title;
-  if (!title) {
-    return null;
-  }
-  for (const prefix of IDEA_TRANSITION_PREFIXES) {
-    if (title.startsWith(prefix)) {
-      if (prefix === "Expedite Idea: ") {
-        const hasIdeaDescriptionSection = artifact.sections.some((s) => s.heading === "Idea Description" && s.level === 2);
-        if (hasIdeaDescriptionSection) {
-          return null;
-        }
-      }
-      const ideaTitle = title.slice(prefix.length);
-      const ideaFilename = titleToFilename(ideaTitle);
-      if (!fileSystem.exists(`${ideasPath}/${ideaFilename}`)) {
-        return {
-          file: artifact.filePath,
-          message: `Idea transition task references non-existent idea: "${ideaTitle}" (expected file "${ideaFilename}" in ideas/)`
-        };
-      }
-      return null;
-    }
-  }
-  return null;
-}
-function validateWorkflowTaskBodySection(artifact, ideasPath, fileSystem) {
-  const violations = [];
-  const title = artifact.title;
-  if (!title)
-    return violations;
-  let matchedPrefix = null;
-  for (const prefix of IDEA_TRANSITION_PREFIXES) {
-    if (title.startsWith(prefix)) {
-      matchedPrefix = prefix;
-      break;
-    }
-  }
-  if (!matchedPrefix)
-    return violations;
-  const expectedHeading = WORKFLOW_PREFIX_TO_SECTION[matchedPrefix];
-  const section = artifact.sections.find((s) => s.heading === expectedHeading && s.level === 2);
-  if (!section) {
-    violations.push({
-      file: artifact.filePath,
-      message: `Workflow task with "${matchedPrefix.trim()}" prefix is missing required "## ${expectedHeading}" section. Add a section with a link to the idea file, e.g.:
-
-## ${expectedHeading}
-
-- [Idea Title](../ideas/idea-slug.md)`
-    });
-    return violations;
-  }
-  if (section.links.length === 0) {
-    violations.push({
-      file: artifact.filePath,
-      message: `"## ${expectedHeading}" section contains no link. Add a markdown link to the idea file, e.g.:
-
-- [Idea Title](../ideas/idea-slug.md)`,
-      line: section.startLine
-    });
-    return violations;
-  }
-  const ideaLinks = section.links.filter((l) => l.target.includes("/ideas/") || l.target.startsWith("../ideas/"));
-  if (ideaLinks.length === 0) {
-    violations.push({
-      file: artifact.filePath,
-      message: `"## ${expectedHeading}" section contains no link to an idea file. Links must point to a file in ../ideas/, e.g.:
-
-- [Idea Title](../ideas/idea-slug.md)`,
-      line: section.startLine
-    });
-    return violations;
-  }
-  for (const link of ideaLinks) {
-    const slugMatch = link.target.match(/([^/]+)\.md$/);
-    if (!slugMatch)
-      continue;
-    const ideaSlug = slugMatch[1];
-    const ideaFilePath = `${ideasPath}/${ideaSlug}.md`;
-    if (!fileSystem.exists(ideaFilePath)) {
-      violations.push({
-        file: artifact.filePath,
-        message: `Link to idea "${link.text}" points to non-existent file: ${ideaSlug}.md. Either create the idea file at ideas/${ideaSlug}.md or update the link to point to an existing idea.`,
-        line: link.line
-      });
-    }
-  }
-  return violations;
-}
 
 // lib/lint/validators/link-validator.ts
 import { dirname, resolve } from "node:path";
@@ -816,6 +763,7 @@ async function parseArtifacts(fileSystem, dustPath) {
     tasks: []
   };
   const rootFiles = [];
+  const customAudits = [];
   const violations = [];
   let rootEntries;
   try {
@@ -874,11 +822,40 @@ async function parseArtifacts(fileSystem, dustPath) {
       byType[dir].push(artifact);
     }
   }
+  const auditsPath = `${dustPath}/config/audits`;
+  let auditEntries;
+  try {
+    auditEntries = await fileSystem.readdir(auditsPath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      auditEntries = [];
+    } else {
+      throw error;
+    }
+  }
+  for (const entry of auditEntries) {
+    if (!entry.endsWith(".md"))
+      continue;
+    const filePath = `${auditsPath}/${entry}`;
+    let content;
+    try {
+      content = await fileSystem.readFile(filePath);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        continue;
+      }
+      throw error;
+    }
+    const artifact = parseArtifact(filePath, content);
+    artifacts.set(filePath, artifact);
+    customAudits.push(artifact);
+  }
   return {
     context: {
       artifacts,
       byType,
       rootFiles,
+      customAudits,
       dustPath,
       fileSystem
     },
@@ -887,8 +864,7 @@ async function parseArtifacts(fileSystem, dustPath) {
 }
 function validateArtifacts(context) {
   const violations = [];
-  const { byType, rootFiles, dustPath, fileSystem } = context;
-  const ideasPath = `${dustPath}/ideas`;
+  const { byType, rootFiles, customAudits, fileSystem } = context;
   for (const artifact of rootFiles) {
     violations.push(...validateLinks(artifact, fileSystem));
   }
@@ -918,10 +894,9 @@ function validateArtifacts(context) {
     const imperativeViolation = validateImperativeOpeningSentence(artifact);
     if (imperativeViolation)
       violations.push(imperativeViolation);
-    const ideaTransitionViolation = validateIdeaTransitionTitle(artifact, ideasPath, fileSystem);
-    if (ideaTransitionViolation)
-      violations.push(ideaTransitionViolation);
-    violations.push(...validateWorkflowTaskBodySection(artifact, ideasPath, fileSystem));
+    const taskTypeViolation = validateTaskType(artifact);
+    if (taskTypeViolation)
+      violations.push(taskTypeViolation);
   }
   const allPrincipleRelationships = [];
   for (const artifact of byType.principles) {
@@ -931,6 +906,18 @@ function validateArtifacts(context) {
   }
   violations.push(...validateBidirectionalLinks(allPrincipleRelationships));
   violations.push(...validateNoCycles(allPrincipleRelationships));
+  for (const artifact of customAudits) {
+    const filenameViolation = validateFilename(artifact.filePath);
+    if (filenameViolation)
+      violations.push(filenameViolation);
+    const openingSentenceViolation = validateOpeningSentence(artifact);
+    if (openingSentenceViolation)
+      violations.push(openingSentenceViolation);
+    const lengthViolation = validateOpeningSentenceLength(artifact);
+    if (lengthViolation)
+      violations.push(lengthViolation);
+    violations.push(...validateAuditHeadings(artifact));
+  }
   return violations;
 }
 
@@ -1194,6 +1181,9 @@ function serializeStandardTask(input) {
   if (input.principles && input.principles.length > 0) {
     sections.push(renderPrinciplesSection(input.principles));
   }
+  sections.push(`## Task Type
+
+implement`);
   sections.push(renderBlockedBySection(input.blockedBy ?? []));
   sections.push(renderDefinitionOfDoneSection(input.definitionOfDone));
   return sections.join(`
@@ -1210,12 +1200,17 @@ function serializeWorkflowTask(input) {
   const ideaSection = `## ${sectionHeading}
 
 - [${ideaTitle}](../ideas/${input.ideaSlug}.md)`;
+  const taskType = input.type === "capture-idea" ? "capture" : input.type === "refine-idea" ? "refine" : input.type === "decompose-idea" ? "decompose" : "shelve";
   return `# ${title}
 
 ${openingSentence}
 
 ${ideaSection}
 
+## Task Type
+
+${taskType}
+
 ## Blocked By
 
 (none)
@@ -1694,5 +1689,7 @@ export {
   serializePrinciple,
   serializeIdea,
   serializeFact,
+  parseArtifactPath,
+  buildPreviews,
   buildArtifactPatch
 };

package/dist/proxy/helper-token.d.ts

@@ -44,7 +44,7 @@ export declare function generateHelperToken(now?: number): HelperToken;
  * @param ttlMs - Time-to-live in milliseconds (defaults to HELPER_TOKEN_TTL_MS)
  * @returns true if the token is valid, false otherwise
  */
-export declare function isHelperTokenValid(token: string, issued: HelperToken, now?: number, ttlMs?: number): boolean;
+export declare function isHelperTokenValid(token: string, issued: HelperToken, now: number, ttlMs: number): boolean;
 /**
  * Create a new helper token state object.
  * The state starts with no current token.
@@ -60,7 +60,7 @@ export declare function createHelperTokenState(): HelperTokenState;
  * @param now - Current timestamp in milliseconds (defaults to Date.now())
  * @returns A new HelperTokenState with a fresh token
  */
-export declare function rotateHelperToken(state: HelperTokenState, now?: number): HelperTokenState;
+export declare function rotateHelperToken(_state: HelperTokenState, now?: number): HelperTokenState;
 /**
  * Check if the current helper token in state is valid.
  * Returns false if there is no current token.

package/dist/session.d.ts

@@ -3,9 +3,11 @@ export declare const DUST_UNATTENDED = "DUST_UNATTENDED";
 export declare const DUST_SKIP_AGENT = "DUST_SKIP_AGENT";
 export declare const DUST_REPOSITORY_ID = "DUST_REPOSITORY_ID";
 export declare const DUST_PROXY_PORT = "DUST_PROXY_PORT";
+export declare const DUST_TRACE_ID = "DUST_TRACE_ID";
 export declare function isUnattended(session: SessionConfig): boolean;
 export declare function buildUnattendedEnv(options: {
     repositoryId?: string;
     proxyPort?: number;
+    traceId?: string;
     session: SessionConfig;
 }): Record<string, string>;

package/dist/validation/validation-pipeline.d.ts

@@ -19,6 +19,7 @@ interface ValidationContext {
         tasks: ParsedArtifact[];
     };
     rootFiles: ParsedArtifact[];
+    customAudits: ParsedArtifact[];
     dustPath: string;
     fileSystem: ReadableFileSystem;
 }