@joshski/dust 0.1.110 → 0.1.111

package/README.md

@@ -47,3 +47,7 @@ Details live in the [.dust/facts](./.dust/facts) directory:
 - [Directory Structure](./.dust/facts/dust-directory-structure.md) — how `.dust/` is organized
 - [Configuration](./.dust/facts/configuration-system.md) — settings and quality checks
 - [CLI Commands](./.dust/facts/unified-cli.md) — full command reference
+
+## Dust Bucket Worker
+
+The `dust bucket worker` command runs a background worker that syncs agent sessions to [dustbucket.com](https://dustbucket.com). This requires a dustbucket.com account (currently in private alpha, invite only).

package/dist/artifacts/facts.d.ts

@@ -1,9 +1,6 @@
 import type { FileReader } from '../filesystem/types';
-export interface Fact {
-    slug: string;
-    title: string;
-    content: string;
-}
+import type { Fact } from './types';
+export type { Fact };
 /**
  * Parses a fact markdown file into a structured Fact object.
  */

package/dist/artifacts/ideas.d.ts

@@ -1,19 +1,6 @@
 import type { FileReader } from '../filesystem/types';
-export interface IdeaOption {
-    name: string;
-    description: string;
-}
-export interface IdeaOpenQuestion {
-    question: string;
-    options: IdeaOption[];
-}
-export interface Idea {
-    slug: string;
-    title: string;
-    openingSentence: string | null;
-    content: string;
-    openQuestions: IdeaOpenQuestion[];
-}
+import type { Idea, IdeaOpenQuestion, IdeaOption } from './types';
+export type { Idea, IdeaOpenQuestion, IdeaOption };
 export interface ParsedIdeaContent {
     title: string | null;
     body: string;

package/dist/artifacts/index.d.ts

@@ -6,21 +6,11 @@ import { type Principle } from './principles';
 import { type Task } from './tasks';
 import { type ParsedArtifact, type ParsedMarkdownLink, type ParsedSection, parseArtifact } from './parsed-artifact';
 import { type AllWorkflowTasks, CAPTURE_IDEA_PREFIX, type CreateIdeaTransitionTaskResult, type DecomposeIdeaOptions, findAllWorkflowTasks, type IdeaInProgress, type OpenQuestionResponse, type ParsedCaptureIdeaTask, parseResolvedQuestions, type TaskType, type WorkflowTaskMatch } from './workflow-tasks';
+import type { ArtifactType, ReadOnlyArtifactsRepository } from './types';
+export type { ArtifactType, ReadOnlyArtifactsRepository, RepositoryPrincipleNode, TaskGraph, TaskGraphNode, } from './types';
 export type { AllWorkflowTasks, CreateIdeaTransitionTaskResult, DecomposeIdeaOptions, Fact, Idea, IdeaOpenQuestion, IdeaOption, OpenQuestionResponse, ParsedArtifact, ParsedCaptureIdeaTask, ParsedIdeaContent, ParsedMarkdownLink, ParsedSection, Principle, Task, TaskType, WorkflowTaskMatch, };
-export interface TaskGraphNode {
-    task: Task;
-    workflowType: TaskType | null;
-}
-export interface TaskGraph {
-    nodes: TaskGraphNode[];
-    edges: Array<{
-        from: string;
-        to: string;
-    }>;
-}
 export { CAPTURE_IDEA_PREFIX, extractTitle, findAllWorkflowTasks, ideaContentToMarkdown, parseArtifact, parseIdeaContent, parseOpenQuestions, parseResolvedQuestions, };
 export type { IdeaInProgress };
-export type ArtifactType = 'ideas' | 'tasks' | 'principles' | 'facts';
 export declare const ARTIFACT_TYPES: ArtifactType[];
 export declare const DUST_PATH_PREFIX = ".dust/";
 /**
@@ -32,32 +22,6 @@ export declare function parseArtifactPath(path: string): {
     type: ArtifactType;
     slug: string;
 } | null;
-export interface ReadOnlyArtifactsRepository {
-    artifactPath(type: ArtifactType, slug: string): string;
-    parseIdea(options: {
-        slug: string;
-    }): Promise<Idea>;
-    listIdeas(): Promise<string[]>;
-    parsePrinciple(options: {
-        slug: string;
-    }): Promise<Principle>;
-    listPrinciples(): Promise<string[]>;
-    parseFact(options: {
-        slug: string;
-    }): Promise<Fact>;
-    listFacts(): Promise<string[]>;
-    parseTask(options: {
-        slug: string;
-    }): Promise<Task>;
-    listTasks(): Promise<string[]>;
-    findWorkflowTaskForIdea(options: {
-        ideaSlug: string;
-    }): Promise<WorkflowTaskMatch | null>;
-    parseCaptureIdeaTask(options: {
-        taskSlug: string;
-    }): Promise<ParsedCaptureIdeaTask | null>;
-    buildTaskGraph(): Promise<TaskGraph>;
-}
 export interface ArtifactsRepository extends ReadOnlyArtifactsRepository {
     createRefineIdeaTask(options: {
         ideaSlug: string;

package/dist/artifacts/principles.d.ts

@@ -1,11 +1,6 @@
 import type { FileReader } from '../filesystem/types';
-export interface Principle {
-    slug: string;
-    title: string;
-    content: string;
-    parentPrinciple: string | null;
-    subPrinciples: string[];
-}
+import type { Principle } from './types';
+export type { Principle };
 /**
  * Parses a principle markdown file into a structured Principle object.
  */

package/dist/artifacts/repository-principle-hierarchy.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Repository Principle Hierarchy API
+ *
+ * Provides pure functional access to build hierarchical trees of principles
+ * from a repository's .dust/principles/ directory.
+ */
+import type { ReadOnlyArtifactsRepository, RepositoryPrincipleNode } from './types';
+/**
+ * Builds a hierarchy tree of repository principles from .dust/principles/.
+ * Returns root nodes (principles with no parent or filtered parent).
+ * Children are sorted alphabetically by title (recursive).
+ *
+ * @param repository - The repository to read principles from
+ * @returns Array of root principle nodes, empty array if no principles exist
+ */
+export declare function getRepositoryPrincipleHierarchy(repository: ReadOnlyArtifactsRepository): Promise<RepositoryPrincipleNode[]>;

package/dist/artifacts/tasks.d.ts

@@ -1,12 +1,6 @@
 import type { FileReader } from '../filesystem/types';
-export interface Task {
-    slug: string;
-    title: string;
-    content: string;
-    principles: string[];
-    blockedBy: string[];
-    definitionOfDone: string[];
-}
+import type { Task } from './types';
+export type { Task };
 /**
  * Parses a task markdown file into a structured Task object.
  */

package/dist/artifacts/types.d.ts

@@ -0,0 +1,98 @@
+export type TaskType = 'implement' | 'capture' | 'refine' | 'decompose' | 'shelve';
+export interface Fact {
+    slug: string;
+    title: string;
+    content: string;
+}
+export interface IdeaOption {
+    name: string;
+    description: string;
+}
+export interface IdeaOpenQuestion {
+    question: string;
+    options: IdeaOption[];
+}
+export interface Idea {
+    slug: string;
+    title: string;
+    openingSentence: string | null;
+    content: string;
+    openQuestions: IdeaOpenQuestion[];
+}
+export interface Principle {
+    slug: string;
+    title: string;
+    content: string;
+    parentPrinciple: string | null;
+    subPrinciples: string[];
+}
+export interface Task {
+    slug: string;
+    title: string;
+    content: string;
+    principles: string[];
+    blockedBy: string[];
+    definitionOfDone: string[];
+}
+export interface OpenQuestionResponse {
+    question: string;
+    chosenOption: string;
+}
+export interface WorkflowTaskMatch {
+    type: TaskType;
+    ideaSlug: string;
+    taskSlug: string;
+    resolvedQuestions: OpenQuestionResponse[];
+}
+export interface ParsedCaptureIdeaTask {
+    ideaTitle: string;
+    ideaDescription: string;
+    expedite: boolean;
+}
+export type ArtifactType = 'ideas' | 'tasks' | 'principles' | 'facts';
+export interface TaskGraphNode {
+    task: Task;
+    workflowType: TaskType | null;
+}
+export interface TaskGraph {
+    nodes: TaskGraphNode[];
+    edges: Array<{
+        from: string;
+        to: string;
+    }>;
+}
+/**
+ * Node in the principle hierarchy tree
+ */
+export interface RepositoryPrincipleNode {
+    slug: string;
+    title: string;
+    children: RepositoryPrincipleNode[];
+}
+export interface ReadOnlyArtifactsRepository {
+    artifactPath(type: ArtifactType, slug: string): string;
+    parseIdea(options: {
+        slug: string;
+    }): Promise<Idea>;
+    listIdeas(): Promise<string[]>;
+    parsePrinciple(options: {
+        slug: string;
+    }): Promise<Principle>;
+    listPrinciples(): Promise<string[]>;
+    parseFact(options: {
+        slug: string;
+    }): Promise<Fact>;
+    listFacts(): Promise<string[]>;
+    parseTask(options: {
+        slug: string;
+    }): Promise<Task>;
+    listTasks(): Promise<string[]>;
+    findWorkflowTaskForIdea(options: {
+        ideaSlug: string;
+    }): Promise<WorkflowTaskMatch | null>;
+    parseCaptureIdeaTask(options: {
+        taskSlug: string;
+    }): Promise<ParsedCaptureIdeaTask | null>;
+    buildTaskGraph(): Promise<TaskGraph>;
+    getRepositoryPrincipleHierarchy(): Promise<RepositoryPrincipleNode[]>;
+}

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

@@ -1,4 +1,6 @@
 import type { FileSystem, ReadableFileSystem } from '../filesystem/types';
+import type { OpenQuestionResponse, ParsedCaptureIdeaTask, TaskType, WorkflowTaskMatch } from './types';
+export type { OpenQuestionResponse, ParsedCaptureIdeaTask, TaskType, WorkflowTaskMatch, };
 export declare const IDEA_TRANSITION_PREFIXES: string[];
 export declare const CAPTURE_IDEA_PREFIX = "Add Idea: ";
 export declare const EXPEDITE_IDEA_PREFIX = "Expedite Idea: ";
@@ -6,11 +8,6 @@ export interface IdeaInProgress {
     taskSlug: string;
     ideaTitle: string;
 }
-export interface ParsedCaptureIdeaTask {
-    ideaTitle: string;
-    ideaDescription: string;
-    expedite: boolean;
-}
 /**
  * Converts a markdown title to the expected filename using deterministic rules:
  * 1. Convert to lowercase
@@ -22,18 +19,11 @@ export interface ParsedCaptureIdeaTask {
  */
 export declare function titleToFilename(title: string): string;
 export declare const VALID_TASK_TYPES: readonly ["implement", "capture", "refine", "decompose", "shelve"];
-export type TaskType = (typeof VALID_TASK_TYPES)[number];
 /**
  * Extracts and validates the task type from the ## Task Type section.
  * Returns the task type if found and valid, null otherwise.
  */
 export declare function parseTaskType(content: string): TaskType | null;
-export interface WorkflowTaskMatch {
-    type: TaskType;
-    ideaSlug: string;
-    taskSlug: string;
-    resolvedQuestions: OpenQuestionResponse[];
-}
 export interface AllWorkflowTasks {
     captureIdeaTasks: IdeaInProgress[];
     workflowTasksByIdeaSlug: Map<string, WorkflowTaskMatch>;
@@ -43,10 +33,6 @@ export declare function findWorkflowTaskForIdea(fileSystem: ReadableFileSystem,
 export interface CreateIdeaTransitionTaskResult {
     filePath: string;
 }
-export interface OpenQuestionResponse {
-    question: string;
-    chosenOption: string;
-}
 export interface DecomposeIdeaOptions {
     ideaSlug: string;
     description?: string;

package/dist/artifacts.js

@@ -294,10 +294,7 @@ async function parsePrinciple(fileSystem, dustPath, slug) {
     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 title = extractTitle(content) || slug;
   const parentPrinciple = extractSingleLinkFromSection(content, "Parent Principle");
   const subPrinciples = extractLinksFromSection(content, "Sub-Principles");
   return {
@@ -999,6 +996,42 @@ async function parseCaptureIdeaTask(fileSystem, dustPath, taskSlug) {
   return { ideaTitle, ideaDescription, expedite };
 }
 
+// lib/artifacts/repository-principle-hierarchy.ts
+function sortNodes(nodes) {
+  nodes.sort((a, b) => a.title.localeCompare(b.title));
+  for (const node of nodes) {
+    sortNodes(node.children);
+  }
+}
+async function getRepositoryPrincipleHierarchy(repository) {
+  const slugs = await repository.listPrinciples();
+  if (slugs.length === 0) {
+    return [];
+  }
+  const principles = await Promise.all(slugs.map((slug) => repository.parsePrinciple({ slug })));
+  const principleSet = new Set(slugs);
+  const nodeBySlug = new Map;
+  for (const p of principles) {
+    nodeBySlug.set(p.slug, {
+      slug: p.slug,
+      title: p.title,
+      children: []
+    });
+  }
+  const roots = [];
+  for (const p of principles) {
+    const node = nodeBySlug.get(p.slug);
+    const parentSlug = p.parentPrinciple;
+    if (!parentSlug || !principleSet.has(parentSlug)) {
+      roots.push(node);
+    } else {
+      nodeBySlug.get(parentSlug).children.push(node);
+    }
+  }
+  sortNodes(roots);
+  return roots;
+}
+
 // lib/artifacts/index.ts
 var ARTIFACT_TYPES = [
   "facts",
@@ -1099,6 +1132,9 @@ function buildReadOperations(fileSystem, dustPath) {
         }
       }
       return { nodes, edges };
+    },
+    async getRepositoryPrincipleHierarchy() {
+      return getRepositoryPrincipleHierarchy(this);
     }
   };
 }

package/dist/bucket/repository-loop.d.ts

@@ -12,7 +12,7 @@ import type { SendAgentEventFn } from '../loop/wire-events';
 import { type RunnerDependencies as CodexRunnerDependencies, run as codexRun } from '../codex/run';
 import type { SendEventFn } from './events';
 import { type LogBuffer } from './log-buffer';
-import type { RepositoryDependencies, RepositoryState } from './repository';
+import type { RepositoryDependencies, RepositoryState } from './repository-types';
 /**
  * Create stdout/stderr callbacks that append to a log buffer.
  * Extracted for testability (v8 coverage limitation on inline callbacks).

package/dist/bucket/repository-types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared types for repository management.
+ *
+ * Extracted to break the cyclic dependency between repository.ts and repository-loop.ts.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import type { run as claudeRun } from '../claude/run';
+import type { FileSystem } from '../cli/types';
+import type { DockerDependencies } from '../docker/docker-agent';
+import type { AuthConfig, RuntimeConfig, SessionConfig } from '../env-config';
+import type { ToolExecutionRequest, ToolExecutionResult } from './command-events-proxy';
+import type { LogBuffer } from './log-buffer';
+import type { RepositoryLifecycleState } from './repository-lifecycle';
+import type { ToolDefinition } from './server-messages';
+export interface Repository {
+    name: string;
+    gitUrl: string;
+    gitSshUrl: string;
+    url: string;
+    id: number;
+    agentProvider?: string;
+    branch?: string;
+}
+export interface RepositoryState {
+    repository: Repository;
+    path: string;
+    logBuffer: LogBuffer;
+    lifecycle: RepositoryLifecycleState;
+    agentStatus: 'idle' | 'busy';
+    wakeUp?: () => void;
+    taskAvailablePending?: boolean;
+}
+export interface RepositoryDependencies {
+    spawn: typeof nodeSpawn;
+    run: typeof claudeRun;
+    fileSystem: FileSystem;
+    sleep: (ms: number) => Promise<void>;
+    getReposDir: () => string;
+    session: SessionConfig;
+    runtime: RuntimeConfig;
+    auth: AuthConfig;
+    /** Optional overrides for Docker dependency functions (for testing) */
+    dockerDeps?: Partial<DockerDependencies>;
+    /** Function to get current tool definitions */
+    getTools?: () => ToolDefinition[];
+    /** Function to get revealed tool families (for progressive disclosure) */
+    getRevealedFamilies?: () => Set<string>;
+    /** Forward tool execution requests to the bucket server */
+    forwardToolExecution?: (request: ToolExecutionRequest) => Promise<ToolExecutionResult>;
+    /** Mark a tool family as revealed (for progressive disclosure) */
+    revealFamily?: (familyName: string) => void;
+    /** Shell runner for pre-flight commands (install, check) */
+    shellRunner?: import('../cli/process-runner').ShellRunner;
+    /** Force Docker mode using bundled default Dockerfile */
+    forceDocker?: boolean;
+    /** Force Apple Container mode using bundled default Dockerfile */
+    forceAppleContainer?: boolean;
+}

package/dist/bucket/repository.d.ts

@@ -4,37 +4,13 @@
  * Git operations live in repository-git.ts.
  * Loop orchestration lives in repository-loop.ts.
  */
-import { spawn as nodeSpawn } from 'node:child_process';
-import { run as claudeRun } from '../claude/run';
 import type { CommandDependencies, FileSystem } from '../cli/types';
-import type { DockerDependencies } from '../docker/docker-agent';
-import { type AuthConfig, type RuntimeConfig, type SessionConfig } from '../env-config';
-import type { ToolExecutionRequest, ToolExecutionResult } from './command-events-proxy';
 import { type BucketEmitFn, type SendEventFn } from './events';
 import { type LogBuffer } from './log-buffer';
-import { type RepositoryLifecycleState } from './repository-lifecycle';
-import type { ToolDefinition } from './server-messages';
+import type { Repository, RepositoryDependencies, RepositoryState } from './repository-types';
 export { cloneRepository, getRepoPath, removeRepository, } from './repository-git';
 export { runRepositoryLoop } from './repository-loop';
-export type { RepositoryLifecycleState } from './repository-lifecycle';
-export interface Repository {
-    name: string;
-    gitUrl: string;
-    gitSshUrl: string;
-    url: string;
-    id: number;
-    agentProvider?: string;
-    branch?: string;
-}
-export interface RepositoryState {
-    repository: Repository;
-    path: string;
-    logBuffer: LogBuffer;
-    lifecycle: RepositoryLifecycleState;
-    agentStatus: 'idle' | 'busy';
-    wakeUp?: () => void;
-    taskAvailablePending?: boolean;
-}
+export type { Repository, RepositoryDependencies, RepositoryState, } from './repository-types';
 /**
  * Interface for the subset of bucket state needed by repository management.
  * Avoids circular dependency between repository.ts and bucket.ts.
@@ -46,32 +22,6 @@ export interface RepositoryManager {
     sendEvent: SendEventFn;
     sessionId: string;
 }
-export interface RepositoryDependencies {
-    spawn: typeof nodeSpawn;
-    run: typeof claudeRun;
-    fileSystem: FileSystem;
-    sleep: (ms: number) => Promise<void>;
-    getReposDir: () => string;
-    session: SessionConfig;
-    runtime: RuntimeConfig;
-    auth: AuthConfig;
-    /** Optional overrides for Docker dependency functions (for testing) */
-    dockerDeps?: Partial<DockerDependencies>;
-    /** Function to get current tool definitions */
-    getTools?: () => ToolDefinition[];
-    /** Function to get revealed tool families (for progressive disclosure) */
-    getRevealedFamilies?: () => Set<string>;
-    /** Forward tool execution requests to the bucket server */
-    forwardToolExecution?: (request: ToolExecutionRequest) => Promise<ToolExecutionResult>;
-    /** Mark a tool family as revealed (for progressive disclosure) */
-    revealFamily?: (familyName: string) => void;
-    /** Shell runner for pre-flight commands (install, check) */
-    shellRunner?: import('../cli/process-runner').ShellRunner;
-    /** Force Docker mode using bundled default Dockerfile */
-    forceDocker?: boolean;
-    /** Force Apple Container mode using bundled default Dockerfile */
-    forceAppleContainer?: boolean;
-}
 /**
  * Handle loop completion: transition lifecycle and reset agent status.
  * Extracted as a named function for testability.

package/dist/bucket/server-messages.d.ts

@@ -1,13 +1,19 @@
 /**
  * Typed server-to-client WebSocket messages for the bucket protocol.
  */
-import type { Repository } from './repository';
 import type { AgentCapability } from './agent-capabilities';
 export interface RepositoryListMessage {
     type: 'repository-list';
     repositories: RepositoryListItem[];
 }
-export interface RepositoryListItem extends Repository {
+export interface RepositoryListItem {
+    name: string;
+    gitUrl: string;
+    gitSshUrl: string;
+    url: string;
+    id: number;
+    agentProvider?: string;
+    branch?: string;
     hasTask: boolean;
 }
 export interface TaskAvailableMessage {

package/dist/dust.js

@@ -7,7 +7,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "@joshski/dust",
-    version: "0.1.110",
+    version: "0.1.111",
     description: "Flow state for AI coding agents",
     type: "module",
     bin: {
@@ -721,7 +721,7 @@ async function loadSettings(cwd, fileSystem, runtime) {
 }
 
 // lib/version.ts
-var DUST_VERSION = "0.1.110";
+var DUST_VERSION = "0.1.111";
 
 // lib/cli/middleware.ts
 function applyMiddleware(middlewares, execute) {
@@ -6246,6 +6246,55 @@ async function findAllWorkflowTasks(fileSystem, dustPath) {
   }
   return { captureIdeaTasks, workflowTasksByIdeaSlug };
 }
+async function findWorkflowTaskForIdea(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 tasksPath = `${dustPath}/tasks`;
+  if (!fileSystem.exists(tasksPath)) {
+    return null;
+  }
+  const files = await fileSystem.readdir(tasksPath);
+  for (const file of files.filter((f) => f.endsWith(".md")).toSorted()) {
+    const content = await fileSystem.readFile(`${tasksPath}/${file}`);
+    const taskSlug = file.replace(/\.md$/, "");
+    const match = findWorkflowMatch(content, ideaSlug, taskSlug);
+    if (match) {
+      return match;
+    }
+  }
+  return null;
+}
+function findWorkflowMatch(content, ideaSlug, taskSlug) {
+  const taskType = parseTaskType(content);
+  if (taskType) {
+    const heading = WORKFLOW_SECTION_HEADINGS.find((h) => h.type === taskType)?.heading;
+    if (heading) {
+      const linkedSlug = extractIdeaSlugFromSection(content, heading);
+      if (linkedSlug === ideaSlug) {
+        return {
+          type: taskType,
+          ideaSlug,
+          taskSlug,
+          resolvedQuestions: parseResolvedQuestions(content)
+        };
+      }
+    }
+  }
+  for (const { type, heading } of WORKFLOW_SECTION_HEADINGS) {
+    const linkedSlug = extractIdeaSlugFromSection(content, heading);
+    if (linkedSlug === ideaSlug) {
+      return {
+        type,
+        ideaSlug,
+        taskSlug,
+        resolvedQuestions: parseResolvedQuestions(content)
+      };
+    }
+  }
+  return null;
+}
 function parseResolvedQuestions(content) {
   const lines = content.split(`
 `);
@@ -6286,6 +6335,42 @@ function parseResolvedQuestions(content) {
   }
   return results;
 }
+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();
+  const taskType = parseTaskType(content);
+  let ideaTitle;
+  let expedite;
+  if (taskType === "implement") {
+    expedite = true;
+    ideaTitle = title.startsWith(EXPEDITE_IDEA_PREFIX) ? title.slice(EXPEDITE_IDEA_PREFIX.length) : title;
+  } else if (taskType === "capture") {
+    expedite = false;
+    ideaTitle = title.startsWith(CAPTURE_IDEA_PREFIX) ? title.slice(CAPTURE_IDEA_PREFIX.length) : title;
+  } else if (title.startsWith(EXPEDITE_IDEA_PREFIX)) {
+    ideaTitle = title.slice(EXPEDITE_IDEA_PREFIX.length);
+    expedite = true;
+  } else if (title.startsWith(CAPTURE_IDEA_PREFIX)) {
+    ideaTitle = title.slice(CAPTURE_IDEA_PREFIX.length);
+    expedite = 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, expedite };
+}
 
 // lib/lint/validators/content-validator.ts
 var REQUIRED_TASK_HEADINGS = ["Task Type", "Blocked By", "Definition of Done"];
@@ -9426,6 +9511,34 @@ function executeMessageEffects(effects, dependencies) {
   }
 }
 
+// lib/bucket/bucket-dependencies.ts
+function createAuthFileSystem(dependencies) {
+  return {
+    exists: (path3) => {
+      try {
+        dependencies.accessSync(path3);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    isDirectory: (path3) => {
+      try {
+        return dependencies.statSync(path3).isDirectory();
+      } catch {
+        return false;
+      }
+    },
+    getFileCreationTime: (path3) => dependencies.statSync(path3).birthtimeMs,
+    readFile: (path3) => dependencies.readFile(path3, "utf8"),
+    writeFile: (path3, content) => dependencies.writeFile(path3, content, "utf8"),
+    mkdir: (path3, options) => dependencies.mkdir(path3, options).then(() => {}),
+    readdir: dependencies.readdir.bind(dependencies),
+    chmod: dependencies.chmod.bind(dependencies),
+    rename: dependencies.rename.bind(dependencies)
+  };
+}
+
 // lib/bucket/native-io.ts
 import { spawn as nodeSpawn4 } from "node:child_process";
 import { EventEmitter } from "node:events";
@@ -9897,32 +10010,6 @@ function findRepoPathByRepositoryId(repositories, repositoryId) {
   return;
 }
 var DEFAULT_DUSTBUCKET_WS_URL = "wss://dustbucket.com/agent/connect";
-function createAuthFileSystem(dependencies) {
-  return {
-    exists: (path3) => {
-      try {
-        dependencies.accessSync(path3);
-        return true;
-      } catch {
-        return false;
-      }
-    },
-    isDirectory: (path3) => {
-      try {
-        return dependencies.statSync(path3).isDirectory();
-      } catch {
-        return false;
-      }
-    },
-    getFileCreationTime: (path3) => dependencies.statSync(path3).birthtimeMs,
-    readFile: (path3) => dependencies.readFile(path3, "utf8"),
-    writeFile: (path3, content) => dependencies.writeFile(path3, content, "utf8"),
-    mkdir: (path3, options) => dependencies.mkdir(path3, options).then(() => {}),
-    readdir: dependencies.readdir.bind(dependencies),
-    chmod: dependencies.chmod.bind(dependencies),
-    rename: dependencies.rename.bind(dependencies)
-  };
-}
 function createInitialState() {
   const sessionId = crypto.randomUUID();
   const systemBuffer = createLogBuffer();
@@ -10732,6 +10819,273 @@ Run \`dust bucket tool ${toolName}\` to see available operations.`);
 // lib/cli/commands/lint-markdown.ts
 import { isAbsolute, join as join11, relative, sep } from "node:path";
 
+// 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;
+    }
+  }
+  let inCodeFence = false;
+  for (const line of lines) {
+    if (line.startsWith("```")) {
+      inCodeFence = !inCodeFence;
+      if (currentOption) {
+        descriptionLines.push(line);
+      }
+      continue;
+    }
+    if (inCodeFence) {
+      if (currentOption) {
+        descriptionLines.push(line);
+      }
+      continue;
+    }
+    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) || slug;
+  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 listMatch = line.match(/^-\s+(.+)$/);
+    if (listMatch) {
+      items.push(listMatch[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/repository-principle-hierarchy.ts
+function sortNodes(nodes) {
+  nodes.sort((a, b) => a.title.localeCompare(b.title));
+  for (const node of nodes) {
+    sortNodes(node.children);
+  }
+}
+async function getRepositoryPrincipleHierarchy(repository) {
+  const slugs = await repository.listPrinciples();
+  if (slugs.length === 0) {
+    return [];
+  }
+  const principles = await Promise.all(slugs.map((slug) => repository.parsePrinciple({ slug })));
+  const principleSet = new Set(slugs);
+  const nodeBySlug = new Map;
+  for (const p of principles) {
+    nodeBySlug.set(p.slug, {
+      slug: p.slug,
+      title: p.title,
+      children: []
+    });
+  }
+  const roots = [];
+  for (const p of principles) {
+    const node = nodeBySlug.get(p.slug);
+    const parentSlug = p.parentPrinciple;
+    if (!parentSlug || !principleSet.has(parentSlug)) {
+      roots.push(node);
+    } else {
+      nodeBySlug.get(parentSlug).children.push(node);
+    }
+  }
+  sortNodes(roots);
+  return roots;
+}
+
 // lib/artifacts/index.ts
 var ARTIFACT_TYPES = [
   "facts",
@@ -10739,6 +11093,90 @@ var ARTIFACT_TYPES = [
   "principles",
   "tasks"
 ];
+function buildReadOperations(fileSystem, dustPath) {
+  return {
+    artifactPath(type, slug) {
+      return `${dustPath}/${type}/${slug}.md`;
+    },
+    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$/, "")).toSorted();
+    },
+    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$/, "")).toSorted();
+    },
+    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$/, "")).toSorted();
+    },
+    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$/, "")).toSorted();
+    },
+    async findWorkflowTaskForIdea(options) {
+      return findWorkflowTaskForIdea(fileSystem, dustPath, options.ideaSlug);
+    },
+    async parseCaptureIdeaTask(options) {
+      return parseCaptureIdeaTask(fileSystem, dustPath, options.taskSlug);
+    },
+    async buildTaskGraph() {
+      const taskSlugs = await this.listTasks();
+      const allWorkflowTasks = await findAllWorkflowTasks(fileSystem, dustPath);
+      const workflowTypeByTaskSlug = new Map;
+      for (const match of allWorkflowTasks.workflowTasksByIdeaSlug.values()) {
+        workflowTypeByTaskSlug.set(match.taskSlug, match.type);
+      }
+      const nodes = [];
+      const edges = [];
+      for (const slug of taskSlugs) {
+        const task = await this.parseTask({ slug });
+        nodes.push({
+          task,
+          workflowType: workflowTypeByTaskSlug.get(slug) ?? null
+        });
+        for (const blockerSlug of task.blockedBy) {
+          edges.push({ from: blockerSlug, to: slug });
+        }
+      }
+      return { nodes, edges };
+    },
+    async getRepositoryPrincipleHierarchy() {
+      return getRepositoryPrincipleHierarchy(this);
+    }
+  };
+}
+function buildReadOnlyArtifactsRepository(fileSystem, dustPath) {
+  return buildReadOperations(fileSystem, dustPath);
+}
 
 // lib/lint/validators/directory-validator.ts
 var EXPECTED_DIRECTORIES = [...ARTIFACT_TYPES, "config"];
@@ -13081,10 +13519,10 @@ Surprising behavior erodes trust and slows people down. Unsurprising behavior le
 ];
 
 // lib/artifacts/core-principles.ts
-function sortNodes(nodes) {
+function sortNodes2(nodes) {
   nodes.sort((a, b) => a.title.localeCompare(b.title));
   for (const node of nodes) {
-    sortNodes(node.children);
+    sortNodes2(node.children);
   }
 }
 function isInternalPrinciple(principleContent) {
@@ -13128,12 +13566,12 @@ function getCorePrincipleTree(allPrinciples, config) {
       nodeBySlug.get(parentSlug).children.push(node);
     }
   }
-  sortNodes(roots);
+  sortNodes2(roots);
   return roots;
 }
 
 // lib/core-principles.ts
-function extractLinksFromSection(content, sectionHeading) {
+function extractLinksFromSection3(content, sectionHeading) {
   const lines = content.split(`
 `);
   const links = [];
@@ -13158,8 +13596,8 @@ function extractLinksFromSection(content, sectionHeading) {
   }
   return links;
 }
-function extractSingleLinkFromSection(content, sectionHeading) {
-  const links = extractLinksFromSection(content, sectionHeading);
+function extractSingleLinkFromSection2(content, sectionHeading) {
+  const links = extractLinksFromSection3(content, sectionHeading);
   return links.length === 1 ? links[0] : null;
 }
 function parsePrincipleContent(slug, content) {
@@ -13167,8 +13605,8 @@ function parsePrincipleContent(slug, content) {
   if (!title) {
     throw new Error(`Principle has no title: ${slug}`);
   }
-  const parentPrinciple = extractSingleLinkFromSection(content, "Parent Principle");
-  const subPrinciples = extractLinksFromSection(content, "Sub-Principles");
+  const parentPrinciple = extractSingleLinkFromSection2(content, "Parent Principle");
+  const subPrinciples = extractLinksFromSection3(content, "Sub-Principles");
   return {
     slug,
     title,
@@ -13377,7 +13815,6 @@ async function init(dependencies) {
 }
 
 // lib/cli/commands/list.ts
-import { basename as basename3 } from "node:path";
 function workflowTypeToStatus(type) {
   switch (type) {
     case "refine":
@@ -13447,41 +13884,7 @@ function formatPrinciplesSection(header, entries) {
   }
   return lines;
 }
-async function buildPrincipleHierarchy(principlesPath, fileSystem) {
-  const files = await fileSystem.readdir(principlesPath);
-  const mdFiles = files.filter((f) => f.endsWith(".md"));
-  const relationships = [];
-  const titleMap = new Map;
-  for (const file of mdFiles) {
-    const filePath = `${principlesPath}/${file}`;
-    const content = await fileSystem.readFile(filePath);
-    const artifact = parseArtifact(filePath, content);
-    relationships.push(extractPrincipleRelationships(artifact));
-    const title = extractTitle(content) || basename3(file, ".md");
-    titleMap.set(filePath, title);
-  }
-  const relMap = new Map;
-  for (const rel of relationships) {
-    relMap.set(rel.filePath, rel);
-  }
-  const rootPrinciples = relationships.filter((rel) => rel.parentPrinciples.length === 0);
-  function buildNode(filePath) {
-    const rel = relMap.get(filePath);
-    const children = [];
-    if (rel) {
-      for (const childPath of rel.subPrinciples) {
-        children.push(buildNode(childPath));
-      }
-    }
-    return {
-      filePath,
-      title: titleMap.get(filePath) || basename3(filePath, ".md"),
-      children
-    };
-  }
-  return rootPrinciples.map((rel) => buildNode(rel.filePath));
-}
-function renderHierarchy(nodes, output, prefix = "") {
+function renderRepositoryPrincipleHierarchy(nodes, output, prefix = "") {
   for (let i = 0;i < nodes.length; i++) {
     const node = nodes[i];
     const isLastNode = i === nodes.length - 1;
@@ -13489,7 +13892,7 @@ function renderHierarchy(nodes, output, prefix = "") {
     const childPrefix = isLastNode ? "    " : "│   ";
     output(`${prefix}${connector}${node.title}`);
     if (node.children.length > 0) {
-      renderHierarchy(node.children, output, prefix + childPrefix);
+      renderRepositoryPrincipleHierarchy(node.children, output, prefix + childPrefix);
     }
   }
 }
@@ -13599,9 +14002,10 @@ async function processPrinciplesList(context) {
       stdout("");
     }
     if (hasLocalPrinciples) {
-      const localHierarchy = await buildPrincipleHierarchy(localDirPath, fileSystem);
+      const repository = buildReadOnlyArtifactsRepository(fileSystem, dustPath);
+      const localHierarchy = await repository.getRepositoryPrincipleHierarchy();
       stdout(`${colors.bold}Local${colors.reset}`);
-      renderHierarchy(localHierarchy, (line) => stdout(line));
+      renderRepositoryPrincipleHierarchy(localHierarchy, (line) => stdout(line));
       stdout("");
       const collectedItems = [];
       for (const file of localMdFiles) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joshski/dust",
-  "version": "0.1.110",
+  "version": "0.1.111",
   "description": "Flow state for AI coding agents",
   "type": "module",
   "bin": {