@joshski/dust 0.1.110 → 0.1.112

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.112",
     description: "Flow state for AI coding agents",
     type: "module",
     bin: {
@@ -56,6 +56,10 @@ var require_package = __commonJS((exports, module) => {
       "./core-principles": {
         import: "./dist/core-principles.js",
         types: "./dist/core-principles.d.ts"
+      },
+      "./execution-order": {
+        import: "./dist/execution-order.js",
+        types: "./dist/execution-order.d.ts"
       }
     },
     files: [
@@ -394,16 +398,22 @@ import {
 // lib/git/file-sorter.ts
 function createGitDirectoryFileSorter(gitRunner) {
   return async (dir, files) => {
-    const timestamps = await Promise.all(files.map(async (file) => {
+    const results = await Promise.all(files.map(async (file) => {
       const result = await gitRunner.run(["log", "-1", "--format=%ct", "--", file], dir);
-      const ts = result.exitCode === 0 ? Number.parseInt(result.output.trim(), 10) : Number.NaN;
-      return {
-        file,
-        timestamp: Number.isNaN(ts) ? Number.POSITIVE_INFINITY : ts
-      };
+      const epochSeconds = result.exitCode === 0 ? Number.parseInt(result.output.trim(), 10) : Number.NaN;
+      const lastCommittedAt = Number.isNaN(epochSeconds) ? null : new Date(epochSeconds * 1000).toISOString();
+      return { file, lastCommittedAt };
     }));
-    timestamps.sort((a, b) => a.timestamp - b.timestamp);
-    return timestamps.map((t) => t.file);
+    results.sort((a, b) => {
+      if (a.lastCommittedAt === null && b.lastCommittedAt === null)
+        return 0;
+      if (a.lastCommittedAt === null)
+        return 1;
+      if (b.lastCommittedAt === null)
+        return -1;
+      return new Date(a.lastCommittedAt).getTime() - new Date(b.lastCommittedAt).getTime();
+    });
+    return results;
   };
 }
 
@@ -721,7 +731,7 @@ async function loadSettings(cwd, fileSystem, runtime) {
 }
 
 // lib/version.ts
-var DUST_VERSION = "0.1.110";
+var DUST_VERSION = "0.1.112";
 
 // lib/cli/middleware.ts
 function applyMiddleware(middlewares, execute) {
@@ -6098,6 +6108,43 @@ function extractFirstSentence2(paragraph) {
   return match ? match[1] : null;
 }
 
+// lib/execution-order.ts
+function computeExecutionOrder(nodes) {
+  if (nodes.length === 0)
+    return [];
+  const sorted = [...nodes].toSorted((a, b) => {
+    if (a.lastCommittedAt === null && b.lastCommittedAt === null)
+      return 0;
+    if (a.lastCommittedAt === null)
+      return 1;
+    if (b.lastCommittedAt === null)
+      return -1;
+    return new Date(a.lastCommittedAt).getTime() - new Date(b.lastCommittedAt).getTime();
+  });
+  const result = [];
+  const completed = new Set;
+  const nodeMap = new Map(nodes.map((n) => [n.slug, n]));
+  while (result.length < nodes.length) {
+    const next = sorted.find((node) => {
+      if (completed.has(node.slug))
+        return false;
+      return node.blockedBy.every((slug) => completed.has(slug) || !nodeMap.has(slug));
+    });
+    if (!next) {
+      for (const node of sorted) {
+        if (!completed.has(node.slug)) {
+          result.push({ node, executionOrder: result.length + 1 });
+          completed.add(node.slug);
+        }
+      }
+      break;
+    }
+    result.push({ node: next, executionOrder: result.length + 1 });
+    completed.add(next.slug);
+  }
+  return result;
+}
+
 // lib/artifacts/workflow-tasks.ts
 var CAPTURE_IDEA_PREFIX = "Add Idea: ";
 var EXPEDITE_IDEA_PREFIX = "Expedite Idea: ";
@@ -6246,6 +6293,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 +6382,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"];
@@ -6390,20 +6522,22 @@ function validateTaskType(artifact) {
 function hasRequiredHeadings(content) {
   return /^## Blocked By\s*$/m.test(content) && /^## Definition of Done\s*$/m.test(content);
 }
-function extractBlockedBy(content) {
+function extractBlockedBySlugs(content) {
   const blockedByMatch = content.match(/^## Blocked By\s*\n([\s\S]*?)(?=\n## |\n*$)/m);
   const section = blockedByMatch[1].trim();
   if (section === "(none)") {
     return [];
   }
   const linkPattern = /\[.*?\]\(([^)]+\.md)\)/g;
-  const blockers = [];
+  const slugs = [];
   let match = linkPattern.exec(section);
   while (match !== null) {
-    blockers.push(match[1]);
+    const slugMatch = match[1].match(/([^/]+)\.md$/);
+    if (slugMatch)
+      slugs.push(slugMatch[1]);
     match = linkPattern.exec(section);
   }
-  return blockers;
+  return slugs;
 }
 async function findUnblockedTasks(cwd, fileSystem, directoryFileSorter) {
   const dustPath = `${cwd}/.dust`;
@@ -6415,19 +6549,20 @@ async function findUnblockedTasks(cwd, fileSystem, directoryFileSorter) {
     return { tasks: [], invalidTasks: [] };
   }
   const files = await fileSystem.readdir(tasksPath);
-  let mdFiles = files.filter((f) => f.endsWith(".md"));
-  if (directoryFileSorter) {
-    mdFiles = await directoryFileSorter(tasksPath, mdFiles);
-  } else {
-    mdFiles.sort((a, b) => {
-      const aTime = fileSystem.getFileCreationTime(`${tasksPath}/${a}`);
-      const bTime = fileSystem.getFileCreationTime(`${tasksPath}/${b}`);
-      return aTime - bTime;
-    });
-  }
+  const mdFiles = files.filter((f) => f.endsWith(".md"));
   if (mdFiles.length === 0) {
     return { tasks: [], invalidTasks: [] };
   }
+  let timestamps;
+  if (directoryFileSorter) {
+    const results = await directoryFileSorter(tasksPath, mdFiles);
+    timestamps = new Map(results.map((r) => [r.file, r.lastCommittedAt]));
+  } else {
+    timestamps = new Map(mdFiles.map((f) => {
+      const ms = fileSystem.getFileCreationTime(`${tasksPath}/${f}`);
+      return [f, ms > 0 ? new Date(ms).toISOString() : null];
+    }));
+  }
   const taskFiles = [];
   for (const file of mdFiles) {
     const filePath = `${tasksPath}/${file}`;
@@ -6448,16 +6583,22 @@ async function findUnblockedTasks(cwd, fileSystem, directoryFileSorter) {
       });
     }
   }
-  const existingTasks = new Set(validTaskFiles.map((t) => t.file));
+  const taskNodes = validTaskFiles.map(({ file, content }) => ({
+    slug: file.replace(/\.md$/, ""),
+    file,
+    content,
+    blockedBy: extractBlockedBySlugs(content),
+    lastCommittedAt: timestamps.get(file) ?? null
+  }));
+  const ordered = computeExecutionOrder(taskNodes);
+  const existingSlugs = new Set(taskNodes.map((t) => t.slug));
   const tasks = [];
-  for (const { file, content } of validTaskFiles) {
-    const blockers = extractBlockedBy(content);
-    const hasIncompleteBlocker = blockers.some((blocker) => existingTasks.has(blocker));
+  for (const { node } of ordered) {
+    const hasIncompleteBlocker = node.blockedBy.some((slug) => existingSlugs.has(slug));
     if (!hasIncompleteBlocker) {
-      const title = extractTitle(content);
-      const openingSentence = extractOpeningSentence(content);
-      const relativePath = `.dust/tasks/${file}`;
-      tasks.push({ path: relativePath, title, openingSentence });
+      const title = extractTitle(node.content);
+      const openingSentence = extractOpeningSentence(node.content);
+      tasks.push({ path: `.dust/tasks/${node.file}`, title, openingSentence });
     }
   }
   return { tasks, invalidTasks };
@@ -9426,6 +9567,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 +10066,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,122 +10875,473 @@ 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/index.ts
-var ARTIFACT_TYPES = [
-  "facts",
-  "ideas",
-  "principles",
-  "tasks"
-];
+// 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/lint/validators/directory-validator.ts
-var EXPECTED_DIRECTORIES = [...ARTIFACT_TYPES, "config"];
-var EXPECTED_ROOT_FILES = ["repository.md"];
-var EXPECTED_CONFIG_FILES = ["settings.json"];
-var EXPECTED_CONFIG_DIRECTORIES = ["audits", "agents", "container", "hints"];
-async function validateContentDirectoryFiles(dirPath, fileSystem) {
-  const violations = [];
-  let entries;
-  try {
-    entries = await fileSystem.readdir(dirPath);
-  } catch (error) {
-    if (isErrorCode(error, "ENOENT")) {
-      return [];
+// 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;
     }
-    throw error;
   }
-  for (const entry of entries) {
-    const entryPath = `${dirPath}/${entry}`;
-    if (entry.startsWith(".")) {
-      violations.push({
-        file: entryPath,
-        message: `Hidden file "${entry}" found in content directory`
-      });
-      continue;
+  function flushQuestion() {
+    flushOption();
+    if (currentQuestion) {
+      questions.push(currentQuestion);
+      currentQuestion = null;
     }
-    if (fileSystem.isDirectory(entryPath)) {
-      violations.push({
-        file: entryPath,
-        message: `Subdirectory "${entry}" found in content directory (content directories should be flat)`
-      });
+  }
+  let inCodeFence = false;
+  for (const line of lines) {
+    if (line.startsWith("```")) {
+      inCodeFence = !inCodeFence;
+      if (currentOption) {
+        descriptionLines.push(line);
+      }
       continue;
     }
-    if (!entry.endsWith(".md")) {
-      violations.push({
-        file: entryPath,
-        message: `Non-markdown file "${entry}" found in content directory`
-      });
+    if (inCodeFence) {
+      if (currentOption) {
+        descriptionLines.push(line);
+      }
+      continue;
     }
-  }
-  return violations;
-}
-async function validateDirectoryStructure(dustPath, fileSystem) {
-  const violations = [];
-  let entries;
-  try {
-    entries = await fileSystem.readdir(dustPath);
-  } catch (error) {
-    if (isErrorCode(error, "ENOENT")) {
-      return [];
+    if (line.startsWith("## ")) {
+      if (inOpenQuestions) {
+        flushQuestion();
+      }
+      inOpenQuestions = line.trimEnd() === "## Open Questions";
+      continue;
     }
-    throw error;
-  }
-  const allowedDirectories = new Set(EXPECTED_DIRECTORIES);
-  const allowedRootFiles = new Set(EXPECTED_ROOT_FILES);
-  const allowedRootList = [
-    ...[...allowedDirectories].toSorted().map((directory) => `${directory}/`),
-    ...EXPECTED_ROOT_FILES
-  ].join(", ");
-  for (const entry of entries) {
-    const entryPath = `${dustPath}/${entry}`;
-    if (entry === "Dockerfile") {
-      violations.push({
-        file: entryPath,
-        message: '".dust/Dockerfile" is no longer supported. Move it to ".dust/config/container/Dockerfile".'
-      });
+    if (!inOpenQuestions)
+      continue;
+    if (line.startsWith("### ")) {
+      flushQuestion();
+      currentQuestion = {
+        question: line.slice(4).trim(),
+        options: []
+      };
       continue;
     }
-    const isDirectory = fileSystem.isDirectory(entryPath);
-    if (!isDirectory) {
-      if (allowedRootFiles.has(entry)) {
-        continue;
+    if (line.startsWith("#### ")) {
+      flushOption();
+      currentOption = {
+        name: line.slice(5).trim(),
+        description: ""
+      };
+      if (currentQuestion) {
+        currentQuestion.options.push(currentOption);
       }
-      violations.push({
-        file: entryPath,
-        message: `Unexpected file "${entry}" in .dust/. Allowed root paths: ${allowedRootList}`
-      });
       continue;
     }
-    if (!allowedDirectories.has(entry)) {
-      violations.push({
-        file: entryPath,
-        message: `Unexpected directory "${entry}" in .dust/. Allowed root paths: ${allowedRootList}`
-      });
+    if (currentOption) {
+      descriptionLines.push(line);
     }
   }
-  const configPath = `${dustPath}/config`;
-  if (!fileSystem.isDirectory(configPath)) {
-    return violations;
+  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})`);
   }
-  let configEntries;
-  try {
-    configEntries = await fileSystem.readdir(configPath);
-  } catch (error) {
-    if (isErrorCode(error, "ENOENT")) {
-      return violations;
-    }
-    throw error;
+  const content = await fileSystem.readFile(ideaPath);
+  const title = extractTitle(content);
+  if (!title) {
+    throw new Error(`Idea file has no title: ${ideaPath}`);
   }
-  const allowedConfigFiles = new Set(EXPECTED_CONFIG_FILES);
-  const allowedConfigDirectories = new Set(EXPECTED_CONFIG_DIRECTORIES);
-  const allowedConfigList = [
-    ...EXPECTED_CONFIG_DIRECTORIES.map((directory) => `${directory}/`),
-    ...EXPECTED_CONFIG_FILES
-  ].toSorted().join(", ");
-  for (const entry of configEntries) {
-    const entryPath = `${configPath}/${entry}`;
-    if (fileSystem.isDirectory(entryPath)) {
-      if (!allowedConfigDirectories.has(entry)) {
+  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",
+  "ideas",
+  "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"];
+var EXPECTED_ROOT_FILES = ["repository.md"];
+var EXPECTED_CONFIG_FILES = ["settings.json"];
+var EXPECTED_CONFIG_DIRECTORIES = ["audits", "agents", "container", "hints"];
+async function validateContentDirectoryFiles(dirPath, fileSystem) {
+  const violations = [];
+  let entries;
+  try {
+    entries = await fileSystem.readdir(dirPath);
+  } catch (error) {
+    if (isErrorCode(error, "ENOENT")) {
+      return [];
+    }
+    throw error;
+  }
+  for (const entry of entries) {
+    const entryPath = `${dirPath}/${entry}`;
+    if (entry.startsWith(".")) {
+      violations.push({
+        file: entryPath,
+        message: `Hidden file "${entry}" found in content directory`
+      });
+      continue;
+    }
+    if (fileSystem.isDirectory(entryPath)) {
+      violations.push({
+        file: entryPath,
+        message: `Subdirectory "${entry}" found in content directory (content directories should be flat)`
+      });
+      continue;
+    }
+    if (!entry.endsWith(".md")) {
+      violations.push({
+        file: entryPath,
+        message: `Non-markdown file "${entry}" found in content directory`
+      });
+    }
+  }
+  return violations;
+}
+async function validateDirectoryStructure(dustPath, fileSystem) {
+  const violations = [];
+  let entries;
+  try {
+    entries = await fileSystem.readdir(dustPath);
+  } catch (error) {
+    if (isErrorCode(error, "ENOENT")) {
+      return [];
+    }
+    throw error;
+  }
+  const allowedDirectories = new Set(EXPECTED_DIRECTORIES);
+  const allowedRootFiles = new Set(EXPECTED_ROOT_FILES);
+  const allowedRootList = [
+    ...[...allowedDirectories].toSorted().map((directory) => `${directory}/`),
+    ...EXPECTED_ROOT_FILES
+  ].join(", ");
+  for (const entry of entries) {
+    const entryPath = `${dustPath}/${entry}`;
+    if (entry === "Dockerfile") {
+      violations.push({
+        file: entryPath,
+        message: '".dust/Dockerfile" is no longer supported. Move it to ".dust/config/container/Dockerfile".'
+      });
+      continue;
+    }
+    const isDirectory = fileSystem.isDirectory(entryPath);
+    if (!isDirectory) {
+      if (allowedRootFiles.has(entry)) {
+        continue;
+      }
+      violations.push({
+        file: entryPath,
+        message: `Unexpected file "${entry}" in .dust/. Allowed root paths: ${allowedRootList}`
+      });
+      continue;
+    }
+    if (!allowedDirectories.has(entry)) {
+      violations.push({
+        file: entryPath,
+        message: `Unexpected directory "${entry}" in .dust/. Allowed root paths: ${allowedRootList}`
+      });
+    }
+  }
+  const configPath = `${dustPath}/config`;
+  if (!fileSystem.isDirectory(configPath)) {
+    return violations;
+  }
+  let configEntries;
+  try {
+    configEntries = await fileSystem.readdir(configPath);
+  } catch (error) {
+    if (isErrorCode(error, "ENOENT")) {
+      return violations;
+    }
+    throw error;
+  }
+  const allowedConfigFiles = new Set(EXPECTED_CONFIG_FILES);
+  const allowedConfigDirectories = new Set(EXPECTED_CONFIG_DIRECTORIES);
+  const allowedConfigList = [
+    ...EXPECTED_CONFIG_DIRECTORIES.map((directory) => `${directory}/`),
+    ...EXPECTED_CONFIG_FILES
+  ].toSorted().join(", ");
+  for (const entry of configEntries) {
+    const entryPath = `${configPath}/${entry}`;
+    if (fileSystem.isDirectory(entryPath)) {
+      if (!allowedConfigDirectories.has(entry)) {
         violations.push({
           file: entryPath,
           message: `Unexpected directory "${entry}" in .dust/config/. Allowed entries: ${allowedConfigList}`
@@ -11720,61 +12214,120 @@ async function check(dependencies, shellRunner, clock, _setInterval, _clearInter
   return { exitCode };
 }
 
-// lib/bundled-core-principles.ts
-var BUNDLED_PRINCIPLES = [
+// lib/bundled-core-principles.ts
+var BUNDLED_PRINCIPLES = [
+  {
+    slug: "design-for-testability",
+    content: `# Design for Testability
+
+Design code to be testable first; good structure follows naturally.
+
+Testability should be a primary design driver, not a quality to be retrofitted. When code is designed to be testable from the start, it naturally becomes decoupled, explicit in its dependencies, and clear in its interfaces.
+
+The discipline of testability forces good design: functions become pure, dependencies become explicit, side effects become isolated. Rather than viewing testability as a tax on production code, recognize it as a compass that points toward better architecture.
+
+This is particularly important in agent-driven development. Agents cannot manually verify their changes—they rely entirely on tests. Code that resists testing resists autonomous modification.
+
+## Parent Principle
+
+- [Decoupled Code](decoupled-code.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
   {
-    slug: "batteries-included",
-    content: `# Batteries Included
+    slug: "fast-feedback-loops",
+    content: `# Fast Feedback Loops
 
-Dust should provide everything that is required (within reason) for an agent to be productive in an arbitrary codebase.
+The primary feedback loop — write code, run checks, see results — should be as fast as possible.
 
-An agent working autonomously should not be blocked because a tool or configuration is missing. For example, dust should ship custom lint rules for different linters, even though those linters are not dependencies of dust itself. If an agent needs a capability to do its job well in a typical codebase, dust should provide it out of the box.
+Fast feedback is the foundation of productive development, for both humans and agents. When tests, linters, and type checks run in seconds rather than minutes, developers iterate more frequently and catch problems earlier. Agents especially benefit because they operate in tight loops of change-and-verify; slow feedback wastes tokens and context window space on waiting rather than working.
 
-This means accepting some breadth of scope — bundling configs, rules, and utilities that target external tools — in exchange for agents that can start producing useful work immediately without manual setup.
+Dust should help projects measure the speed of their feedback loops, identify bottlenecks, and keep them fast as the codebase grows. This includes promoting practices like unit tests over integration tests for speed, incremental compilation, and check parallelisation.
 
-## Applicability
+## Parent Principle
 
-Internal
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "test-isolation",
+    content: `# Test Isolation
+
+Tests should not interfere with one another. Each test must be independently runnable and produce the same result regardless of execution order or which other tests run alongside it.
+
+This means:
+- No shared mutable state between tests
+- No reliance on test execution order
+- No file system or environment pollution
+- Each test sets up its own dependencies
+
+Test isolation enables parallel execution, makes failures easier to diagnose, and prevents cascading false failures when one test breaks.
 
 ## Parent Principle
 
-- [Agent Autonomy](agent-autonomy.md)
+- [Make Changes with Confidence](make-changes-with-confidence.md)
 
 ## Sub-Principles
+
+- [Environment-Independent Tests](environment-independent-tests.md)
 `
   },
   {
-    slug: "some-big-design-up-front",
-    content: `# Some Big Design Up Front
+    slug: "boy-scout-rule",
+    content: `# Boy Scout Rule
 
-AI agents lower the cost of architectural exploration, making heavier upfront investment rational during the idea phase.
+Always leave the code better than you found it.
 
-Agile's rejection of "big design up front" (BDUF) was largely economic: detailed architecture was expensive to produce and often wrong. AI agents change that equation — they can explore multiple variants, prototype them, and measure trade-offs cheaply. When evaluating alternatives costs less, the expected value of avoiding large structural mistakes increases.
+When working in any area of the codebase, take the opportunity to make small improvements — clearer names, removed dead code, better structure — even if they're not directly related to the task at hand. These incremental improvements compound over time, preventing gradual decay and keeping the codebase healthy without requiring dedicated cleanup efforts.
 
-This doesn't mean returning to traditional BDUF. Uncertainty about future requirements still limits what prediction can achieve. The insight is that the optimal amount of upfront work has shifted, not that prediction became reliable.
+The Boy Scout Rule is not a license for large-scale refactoring during unrelated work. Improvements should be small, obvious, and low-risk. If a cleanup is too large to include alongside the current task, capture it as a separate task instead.
 
-The model is hybrid: thorough AI-assisted exploration during ideas, followed by straightforward execution during tasks. "Lightweight" refers to task-level planning, not idea-level exploration. Invest heavily in understanding alternatives during the idea phase, then decompose into atomic tasks once the direction is clear.
+## Parent Principle
 
-## Convergence Criteria
+- [Maintainable Codebase](maintainable-codebase.md)
 
-Exploration should continue until clear trade-offs are identified and the chosen approach can be articulated against alternatives. This is convergence-based, not time-boxed — simple ideas converge quickly, complex architectural decisions require more exploration.
+## Sub-Principles
 
-When exploration feels "done":
+- (none)
+`
+  },
+  {
+    slug: "atomic-commits",
+    content: `# Atomic Commits
 
-- Multiple approaches have been considered
-- Trade-offs between approaches are understood
-- The chosen direction has clear justification
-- Remaining uncertainty is about requirements, not design
+Each commit should tell a complete story, bundling implementation changes with their corresponding documentation updates.
 
-If a task requires significant design decisions during execution, it wasn't ready to be a task.
+When a task is completed, the commit deletes the task file, updates relevant facts to reflect the new reality, and removes any ideas that have been realized. This discipline ensures that any point in the commit history represents a coherent, self-documenting state of the project.
 
-## Documenting Alternatives
+Clean commit history is essential because archaeology depends on it. Future humans and AI agents will traverse history to understand why decisions were made and how the system evolved.
 
-Ideas should document the alternatives considered and why they were ruled out. This creates a decision log that helps future agents and humans understand context. Include alternatives in the idea body or Open Questions sections.
+## Parent Principle
+
+- [Repository Hygiene](repository-hygiene.md)
+
+## Sub-Principles
+
+- [Traceable Decisions](traceable-decisions.md)
+`
+  },
+  {
+    slug: "co-located-tests",
+    content: `# Co-located Tests
+
+Test files should live next to the code they test.
+
+When tests are co-located with their source files, developers can immediately see what's tested and what isn't. Finding the test for a module becomes trivial—it's right there in the same directory. This proximity encourages writing tests as part of the development flow rather than as an afterthought, and makes it natural to update tests when modifying code.
 
 ## Parent Principle
 
-- [Lightweight Planning](lightweight-planning.md)
+- [Intuitive Directory Structure](intuitive-directory-structure.md)
 
 ## Sub-Principles
 
@@ -11782,20 +12335,20 @@ Ideas should document the alternatives considered and why they were ruled out. T
 `
   },
   {
-    slug: "design-for-testability",
-    content: `# Design for Testability
+    slug: "broken-windows",
+    content: `# Broken Windows
 
-Design code to be testable first; good structure follows naturally.
+Don't leave broken windows unrepaired.
 
-Testability should be a primary design driver, not a quality to be retrofitted. When code is designed to be testable from the start, it naturally becomes decoupled, explicit in its dependencies, and clear in its interfaces.
+A broken window — a bad name, a hack, a TODO that lingers, a test that's been skipped — signals that nobody cares. That signal invites more neglect. One shortcut becomes two, then ten, and the codebase quietly rots from the inside.
 
-The discipline of testability forces good design: functions become pure, dependencies become explicit, side effects become isolated. Rather than viewing testability as a tax on production code, recognize it as a compass that points toward better architecture.
+When you spot a broken window, fix it immediately if the fix is small. If it's too large, capture it as a task so it doesn't get forgotten. The key is to never normalise the damage. Even a comment acknowledging the problem ("this needs fixing because...") is better than silent acceptance.
 
-This is particularly important in agent-driven development. Agents cannot manually verify their changes—they rely entirely on tests. Code that resists testing resists autonomous modification.
+This principle complements the [Boy Scout Rule](boy-scout-rule.md): the Boy Scout Rule encourages proactive improvement, while Broken Windows warns against tolerating known problems. Together they keep entropy at bay.
 
 ## Parent Principle
 
-- [Decoupled Code](decoupled-code.md)
+- [Maintainable Codebase](maintainable-codebase.md)
 
 ## Sub-Principles
 
@@ -11803,97 +12356,184 @@ This is particularly important in agent-driven development. Agents cannot manual
 `
   },
   {
-    slug: "readable-test-data",
-    content: `# Readable Test Data
+    slug: "trunk-based-development",
+    content: `# Trunk-Based Development
 
-Test data setup should use natural structures that mirror what they represent.
+Dust is designed to support a non-branching workflow where developers commit directly to a single main branch.
 
-## Why it matters
+In trunk-based development, teams collaborate on code in one primary branch rather than maintaining multiple long-lived feature branches. This eliminates merge conflicts, enables continuous integration, and keeps the codebase continuously releasable.
 
-When test data is easy to read, tests become self-documenting. A file system hierarchy expressed as a nested object immediately conveys structure, while a flat Map with path strings requires mental parsing to understand the relationships.
+The \`dust loop claude\` command embodies this philosophy: agents pull from main, implement a task, and push directly back to main. There are no feature branches, no pull requests, no merge queues. Each commit is atomic and complete.
+
+This approach scales through discipline rather than isolation. Feature flags and incremental changes replace long-running branches. The repository history becomes a linear sequence of working states.
+
+See: https://trunkbaseddevelopment.com/
+
+## Parent Principle
+
+- [Repository Hygiene](repository-hygiene.md)
+
+## Sub-Principles
+
+(none)
+`
+  },
+  {
+    slug: "environment-independent-tests",
+    content: `# Environment-Independent Tests
+
+Tests must produce the same result regardless of where they run. A test that passes locally but fails in CI (or vice versa) is a broken test.
+
+Concretely, tests should never depend on:
+- Ambient environment variables (e.g. \`CLAUDECODE\`, \`CI\`, \`HOME\`)
+- The current working directory or filesystem layout of the host machine
+- Network availability or external services
+- The identity of the user or agent running the tests
+
+When a function's behavior depends on environment variables, the test must explicitly control those variables (via \`stubEnv\`, dependency injection, or passing an \`env\` parameter) rather than relying on whatever happens to be set in the current shell.
+
+## Parent Principle
+
+- [Test Isolation](test-isolation.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "comprehensive-assertions",
+    content: `# Comprehensive Assertions
+
+Assert the whole, not the parts.
+
+When you break a complex object into many small assertions, a failure tells you *one thing that's wrong*. When you assert against the whole expected value, the diff tells you *what actually happened versus what you expected* — the full picture, in one glance.
+
+Small assertions are like yes/no questions to a witness. A whole-object assertion is like asking "tell me what you saw."
 
 ## In practice
 
-Prefer literal structures that visually match the domain:
+Collapse multiple partial assertions into one comprehensive assertion:
 
 \`\`\`javascript
-// Avoid: flat paths that obscure hierarchy
-const fs = createFileSystemEmulator({
-  files: new Map([['/project/.dust/principles/my-goal.md', '# My Goal']]),
-  existingPaths: new Set(['/project/.dust/ideas']),
-})
+// Fragmented — each failure is a narrow keyhole
+expect(result.name).toBe("Alice");
+expect(result.age).toBe(30);
+expect(result.role).toBe("admin");
 
-// Prefer: nested object that mirrors file system structure
-const fs = createFileSystemEmulator({
-  project: {
-    '.dust': {
-      principles: {
-        'my-goal.md': '# My Goal'
-      },
-      ideas: {}
-    }
-  }
-})
+// Whole — a failure diff tells the full story
+expect(result).toEqual({
+  name: "Alice",
+  age: 30,
+  role: "admin",
+});
 \`\`\`
 
-The nested form:
-- Shows parent-child relationships through indentation
-- Makes empty directories explicit with empty objects
-- Requires no mental path concatenation to understand structure
+If \`role\` is \`"user"\` and \`age\` is \`29\`, the fragmented version stops at the first failure. The whole-object assertion shows both discrepancies at once, in context.
+
+The same applies to arrays:
+
+\`\`\`javascript
+// Avoid: partial assertions that hide the actual state
+expect(array).toContain('apples')
+expect(array).toContain('oranges')
+
+// Prefer: one assertion that reveals the full picture on failure
+expect(array).toEqual(['apples', 'oranges'])
+\`\`\`
 
 ## How to evaluate
 
-Work supports this principle when test setup data uses structures that visually resemble what they represent, reducing cognitive load for readers.
+Work supports this principle when test failures tell a rich story — showing the complete actual value alongside the complete expected value, so the reader can understand what happened without re-running anything.
+
+## Parent Principle
+
+- [Make Changes with Confidence](make-changes-with-confidence.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "maintainable-codebase",
+    content: `# Maintainable Codebase
+
+The dust codebase should be easy to understand, modify, and extend.
+
+This principle governs how we develop and maintain dust itself, separate from the principles that describe what dust offers its users. A well-maintained codebase enables rapid iteration, reduces bugs, and makes contributions easier.
 
 ## Parent Principle
 
+- [Agentic Flow State](agentic-flow-state.md)
+
+## Sub-Principles
+
 - [Make Changes with Confidence](make-changes-with-confidence.md)
+- [Minimal Dependencies](minimal-dependencies.md)
+- [Intuitive Directory Structure](intuitive-directory-structure.md)
+- [Repository Hygiene](repository-hygiene.md)
+- [Naming Matters](naming-matters.md)
+- [Reasonably DRY](reasonably-dry.md)
+- [Make the Change Easy](make-the-change-easy.md)
+- [Boy Scout Rule](boy-scout-rule.md)
+- [Broken Windows](broken-windows.md)
+`
+  },
+  {
+    slug: "context-window-efficiency",
+    content: `# Context Window Efficiency
+
+Dust should be designed with short attention spans in mind.
+
+AI agents operate within limited context windows. Every token consumed by planning artifacts is a token unavailable for reasoning about code. Dust keeps artifacts concise and scannable so agents can quickly understand what needs to be done without wading through verbose documentation.
+
+This means favoring brevity over completeness, using consistent structures that are fast to parse, and avoiding redundant information across files.
+
+## Parent Principle
+
+- [Agent Autonomy](agent-autonomy.md)
 
 ## Sub-Principles
 
-- (none)
+- [Progressive Disclosure](progressive-disclosure.md)
 `
   },
   {
-    slug: "agent-specific-enhancement",
-    content: `# Agent-Specific Enhancement
-
-Dust should detect and enhance the experience for specific agents while remaining agnostic at its core.
-
-While Dust has [Agent-Agnostic Design](agent-agnostic-design.md) and works with any capable agent, it can still optimize the "agent DX" (developer experience) when it detects a specific agent is being used. This means:
-
-- **Detection** - Dust may detect which agent is running (e.g., Claude Code, Aider, Cursor) through environment variables, configuration, or other signals
-- **Enhancement** - Once detected, Dust can tailor its output format, prompts, or context to leverage that agent's specific strengths
-- **Graceful fallback** - When no specific agent is detected, Dust provides a generic experience that works with any agent
+    slug: "human-ai-collaboration",
+    content: `# Human-AI Collaboration
 
-This principle complements Agent-Agnostic Design: the core functionality never requires a specific agent, but the experience improves when one is recognized.
+Dust exists to enable effective collaboration between humans and AI agents on complex projects.
 
-## Applicability
+The human is the CEO — they set direction, make strategic decisions, and check in when it matters. Dust is the PM — it manages the work, prepares context, and brings fully-researched questions to the human rather than expecting them to drive every detail. Agents are the developers — they read code, write changes, and iterate autonomously.
 
-Internal
+Today's AI coding tools keep humans in a tight loop with agents. Dust is designed to loosen that loop, so humans spend less time directing and more time deciding.
 
 ## Parent Principle
 
-- [Agent Autonomy](agent-autonomy.md)
+- [Agentic Flow State](agentic-flow-state.md)
 
 ## Sub-Principles
 
-- (none)
+- [Agent Autonomy](agent-autonomy.md)
+- [Easy Adoption](easy-adoption.md)
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+- [Lightweight Planning](lightweight-planning.md)
 `
   },
   {
-    slug: "context-optimised-code",
-    content: `# Context-Optimised Code
+    slug: "functional-core-imperative-shell",
+    content: `# Functional Core, Imperative Shell
 
-Code should be structured so that agents can understand and modify it within their context window constraints.
+Separate code into a pure "functional core" and a thin "imperative shell." The core takes values in and returns values out, with no side effects. The shell handles I/O and wires things together.
 
-Large files, deeply nested abstractions, and sprawling dependency chains all work against agents. A 3,000-line file cannot be fully loaded into context. A function that requires understanding six levels of indirection demands more context than one that is self-contained. Context-optimised code favours small files, shallow abstractions, explicit dependencies, and co-located related logic.
+Purely functional code makes some things easier to understand: because values don't change, you can call functions and know that only their return value matters—they don't change anything outside themselves.
 
-Dust should help projects identify files that are too large, modules that are too tangled, and patterns that make agent comprehension harder than it needs to be. This is not just about file size — it is about ensuring that the unit of code an agent needs to understand fits comfortably within the window available.
+The functional core contains business logic as pure functions that take values and return values. The imperative shell sits at the boundary, reading input, calling into the core, and performing side effects with the results. This keeps the majority of code easy to test (no mocks or stubs needed for pure functions) and makes the I/O surface area small and explicit.
 
 ## Parent Principle
 
-- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+- [Decoupled Code](decoupled-code.md)
 
 ## Sub-Principles
 
@@ -11901,57 +12541,45 @@ Dust should help projects identify files that are too large, modules that are to
 `
   },
   {
-    slug: "self-diagnosing-tests",
-    content: `# Self-Diagnosing Tests
-
-When a big test fails, it should be self-evident how to diagnose and fix the failure.
+    slug: "keep-unit-tests-pure",
+    content: `# Keep Unit Tests Pure
 
-The more moving parts a test has — end-to-end, system, integration — the more critical this becomes. A test that fails with \`expected true, received false\` forces the developer (or agent) to re-run, add logging, and guess. A test that fails with a rich diff showing the actual state versus the expected state turns diagnosis into reading.
+Unit tests (those run very frequently as part of a tight feedback loop) should be pure and side-effect free. A test is **not** a unit test if it:
 
-## Anti-patterns
+- Accesses a database
+- Communicates over a network
+- Touches the file system
+- Cannot run concurrently with other tests
+- Requires special environment setup
 
-**Boolean flattening** — collapsing a rich value into true/false before asserting:
-\`\`\`javascript
-// Bad: "expected true, received false" — what events arrived?
-expect(events.some(e => e.type === 'check-passed')).toBe(true)
+"Unit tests" here means tests run frequently during development — not system tests, which intentionally exercise the full stack including I/O. Pure unit tests exercise only business logic, not infrastructure.
 
-// Good: shows the actual event types on failure
-expect(events.map(e => e.type)).toContain('check-passed')
-\`\`\`
+The value of pure unit tests is that they are fast, deterministic, and isolate business logic from infrastructure concerns. When unit tests pass but integration or system tests fail, developers can immediately narrow the problem to the boundary layer — a diagnostic "binary chop" that accelerates debugging.
 
-**Length-only assertions** — checking count without showing contents:
-\`\`\`javascript
-// Bad: "expected 2, received 0" — what requests were captured?
-expect(requests.length).toBe(2)
+## Migration Guidance
 
-// Good: shows the actual requests on failure
-expect(requests).toHaveLength(2)  // vitest shows the array
-\`\`\`
+Where existing tests are impure (e.g. they spawn processes, write temporary files, or make network calls), prefer converting them to use in-memory alternatives — stubs, fakes, or dependency-injected doubles — rather than leaving them as-is. Opportunistic migration is fine; a big-bang rewrite is not required.
 
-**Silent guards** — using \`if\` where an assertion belongs:
-\`\`\`javascript
-// Bad: silently passes when settings is undefined
-if (settings) {
-  expect(JSON.parse(settings).key).toBeDefined()
-}
+## Parent Principle
 
-// Good: fails explicitly if settings is missing
-expect(settings).toBeDefined()
-const parsed = JSON.parse(settings!)
-expect(parsed.key).toBeDefined()
-\`\`\`
+- [Make Changes with Confidence](make-changes-with-confidence.md)
 
-## The test
+## Sub-Principles
 
-If a test fails, can a developer who has never seen the code identify the problem from the failure output alone — without re-running, adding console.logs, or reading the test source? The closer to "yes", the better.
+- (none)
+`
+  },
+  {
+    slug: "runtime-agnostic-tests",
+    content: `# Runtime Agnostic Tests
 
-## How to evaluate
+Dust's test suite should work across JavaScript runtimes.
 
-Work supports this principle when every assertion in a system or integration test would, on failure, reveal the actual state richly enough to guide a fix. Bare boolean checks, length-only assertions, and silent conditional guards are violations.
+Tests should use standard JavaScript testing patterns that work across Node.js, Bun, and other runtimes. Avoiding runtime-specific test APIs ensures the project can leverage different runtimes' advantages while maintaining broad compatibility.
 
 ## Parent Principle
 
-- [Make Changes with Confidence](make-changes-with-confidence.md)
+- [Minimal Dependencies](minimal-dependencies.md)
 
 ## Sub-Principles
 
@@ -11959,48 +12587,35 @@ Work supports this principle when every assertion in a system or integration tes
 `
   },
   {
-    slug: "ideal-agent-developer-experience",
-    content: `# Ideal Agent Developer Experience
-
-The agent is the developer. The human is the CEO. Dust is the PM.
+    slug: "unsurprising-ux",
+    content: `# Unsurprising UX
 
-With today's AI coding assistants, the human is stuck in a tight loop with agents — constantly directing, reviewing, and course-correcting. Dust is designed to relieve humans from this tight loop. Like an assistant to a CEO, dust predominantly brings fully-researched questions and well-prepared work to the human, rather than expecting the human to drive every decision. The human checks in less frequently, and when they do, they make high-leverage strategic calls rather than micromanaging implementation.
+The user interface should be as "guessable" as possible.
 
-For this to work, the agent's development environment must be excellent. The agent reads the code, writes changes, runs the checks, and iterates until the task is done. Everything about the codebase and its tooling either helps or hinders that process. Comprehensive tests are the agent's only way to verify correctness. Fast feedback loops are the agent's iteration speed. Structured logs are the agent's eyes into runtime behaviour. Small, well-organised files are what fit in the agent's context window. Exploratory and debugging tools are how the agent navigates and diagnoses without trial and error.
+Following the [Principle of Least Astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment), users form expectations about how a tool will behave based on conventions, prior experience, and intuition. Dust's interface (including the CLI) should match those expectations wherever possible. If users are observed trying to use the interface in ways we didn't anticipate, the interface should be adjusted to meet their expectations — even if that means supporting many ways of achieving the same result.
 
-Each sub-principle represents a different aspect of the ideal agent developer setup. The better these are, the less the human needs to be in the loop.
+Surprising behavior erodes trust and slows people down. Unsurprising behavior lets users stay in flow.
 
 ## Parent Principle
 
-- [Human-AI Collaboration](human-ai-collaboration.md)
+- [Easy Adoption](easy-adoption.md)
 
 ## Sub-Principles
 
-- [Comprehensive Test Coverage](comprehensive-test-coverage.md)
-- [Fast Feedback Loops](fast-feedback-loops.md)
-- [Slow Feedback Coping](slow-feedback-coping.md)
-- [Development Traceability](development-traceability.md)
-- [Context-Optimised Code](context-optimised-code.md)
-- [Exploratory Tooling](exploratory-tooling.md)
-- [Debugging Tooling](debugging-tooling.md)
-- [Self-Contained Repository](self-contained-repository.md)
+- (none)
 `
   },
   {
-    slug: "broken-windows",
-    content: `# Broken Windows
-
-Don't leave broken windows unrepaired.
-
-A broken window — a bad name, a hack, a TODO that lingers, a test that's been skipped — signals that nobody cares. That signal invites more neglect. One shortcut becomes two, then ten, and the codebase quietly rots from the inside.
+    slug: "unit-test-coverage",
+    content: `# Unit Test Coverage
 
-When you spot a broken window, fix it immediately if the fix is small. If it's too large, capture it as a task so it doesn't get forgotten. The key is to never normalise the damage. Even a comment acknowledging the problem ("this needs fixing because...") is better than silent acceptance.
+Complete unit test coverage ensures low-level tests give users direct feedback as they change the code.
 
-This principle complements the [Boy Scout Rule](boy-scout-rule.md): the Boy Scout Rule encourages proactive improvement, while Broken Windows warns against tolerating known problems. Together they keep entropy at bay.
+Excluding system tests from coverage reporting focuses attention on unit tests - the tests that provide the fastest, most specific feedback. When coverage tools only measure unit tests, developers can quickly identify which parts of the codebase lack fine-grained test protection.
 
 ## Parent Principle
 
-- [Maintainable Codebase](maintainable-codebase.md)
+- [Make Changes with Confidence](make-changes-with-confidence.md)
 
 ## Sub-Principles
 
@@ -12008,18 +12623,22 @@ This principle complements the [Boy Scout Rule](boy-scout-rule.md): the Boy Scou
 `
   },
   {
-    slug: "progressive-disclosure",
-    content: `# Progressive Disclosure
+    slug: "cross-platform-compatibility",
+    content: `# Cross-Platform Compatibility
 
-Dust should reveal details progressively as a way of achieving context window efficiency.
+Dust should work consistently across operating systems: Linux, macOS, and Windows.
 
-Not all information is needed at once. A task list showing just titles is sufficient for choosing what to work on. Full task details are only needed when actively implementing. Linked principles and facts can be followed when deeper context is required.
+This means:
+- Avoiding platform-specific shell commands or syntax
+- Using cross-platform path handling
+- Testing on multiple platforms when possible
+- Documenting any platform-specific limitations
 
-This layered approach keeps initial reads lightweight while preserving access to complete information when needed.
+Cross-platform support broadens adoption and ensures teams with mixed environments can collaborate effectively.
 
 ## Parent Principle
 
-- [Context Window Efficiency](context-window-efficiency.md)
+- [Easy Adoption](easy-adoption.md)
 
 ## Sub-Principles
 
@@ -12027,34 +12646,33 @@ This layered approach keeps initial reads lightweight while preserving access to
 `
   },
   {
-    slug: "lightweight-planning",
-    content: `# Lightweight Planning
-
-Dust aims to be a minimal, low-overhead planning system that stays relevant over time.
+    slug: "vcs-independence",
+    content: `# VCS Independence
 
-Planning artifacts are simple markdown files that live alongside code. Ideas are intentionally vague until implementation is imminent. Tasks are small and completable in single commits. Facts document current reality rather than aspirational states.
+Dust should work independently of any specific version control system.
 
-The system avoids the staleness problem by deferring detail until the last responsible moment and deleting completed work rather than archiving it.
+While git is common, dust's core functionality should not require git. This enables use in repositories using other VCS (Mercurial, SVN, Perforce) or in non-VCS workflows.
 
 ## Parent Principle
 
-- [Human-AI Collaboration](human-ai-collaboration.md)
+- [Easy Adoption](easy-adoption.md)
 
 ## Sub-Principles
 
-- [Task-First Workflow](task-first-workflow.md)
-- [Some Big Design Up Front](some-big-design-up-front.md)
+- (none)
 `
   },
   {
-    slug: "comprehensive-test-coverage",
-    content: `# Comprehensive Test Coverage
+    slug: "self-contained-repository",
+    content: `# Self-Contained Repository
 
-A project's test suite is its primary safety net, and agents depend on it even more than humans do.
+Where possible, developers and agents should have everything they need to be productive, within the repository.
 
-Agents cannot manually verify that their changes work. They rely entirely on automated tests to confirm correctness. Gaps in test coverage become gaps in agent capability — areas where changes are risky and feedback is absent. Comprehensive coverage means every meaningful behaviour is tested, so agents can make changes anywhere in the codebase with confidence.
+No third-party tools should be required beyond those that can be installed with a single command defined in the repository. Setup instructions, scripts, configuration, and dependencies should all live in version control so that cloning the repo and running a single install command is sufficient to start working. This eliminates onboarding friction, reduces "works on my machine" issues, and is especially important for agents — who cannot browse the web to find missing tools or ask colleagues how to set things up.
 
-Dust should help projects measure and improve their test coverage, flag untested areas, and encourage a culture where new code comes with new tests.
+## Applicability
+
+Internal
 
 ## Parent Principle
 
@@ -12066,12 +12684,12 @@ Dust should help projects measure and improve their test coverage, flag untested
 `
   },
   {
-    slug: "intuitive-directory-structure",
-    content: `# Intuitive Directory Structure
+    slug: "minimal-dependencies",
+    content: `# Minimal Dependencies
 
-Code should be organized around related concerns in clearly named directories.
+Dust should avoid coupling to specific tools so we can switch to better alternatives as they emerge.
 
-When files that serve similar purposes are grouped together, the codebase becomes easier to navigate and understand. A developer looking for "commands" should find them in a \`commands\` directory. Utilities should live with utilities. This organization reduces cognitive load and makes the project structure self-documenting.
+By keeping dependencies minimal and using standard APIs where possible, we maintain the freedom to adopt new tools without major rewrites. This applies to runtimes, test frameworks, build tools, and other infrastructure choices.
 
 ## Parent Principle
 
@@ -12079,20 +12697,26 @@ When files that serve similar purposes are grouped together, the codebase become
 
 ## Sub-Principles
 
-- [Co-located Tests](co-located-tests.md)
+- [Runtime Agnostic Tests](runtime-agnostic-tests.md)
 `
   },
   {
-    slug: "small-units",
-    content: `# Small Units
+    slug: "agent-specific-enhancement",
+    content: `# Agent-Specific Enhancement
 
-Ideas, principles, facts, and tasks should each be as discrete and fine-grained as possible.
+Dust should detect and enhance the experience for specific agents while remaining agnostic at its core.
 
-Small, focused documents enable precise relationships between them. A task can link to exactly the principles it serves. A fact can describe one specific aspect of the system. This granularity reduces ambiguity.
+While Dust has [Agent-Agnostic Design](agent-agnostic-design.md) and works with any capable agent, it can still optimize the "agent DX" (developer experience) when it detects a specific agent is being used. This means:
 
-Tasks especially benefit from being small. A narrowly scoped task gives agents or humans the best chance of delivering exactly what was intended, in a single atomic commit.
+- **Detection** - Dust may detect which agent is running (e.g., Claude Code, Aider, Cursor) through environment variables, configuration, or other signals
+- **Enhancement** - Once detected, Dust can tailor its output format, prompts, or context to leverage that agent's specific strengths
+- **Graceful fallback** - When no specific agent is detected, Dust provides a generic experience that works with any agent
 
-Note: This principle directly supports [Lightweight Planning](lightweight-planning.md), which explicitly mentions that "Tasks are small and completable in single commits."
+This principle complements Agent-Agnostic Design: the core functionality never requires a specific agent, but the experience improves when one is recognized.
+
+## Applicability
+
+Internal
 
 ## Parent Principle
 
@@ -12104,48 +12728,53 @@ Note: This principle directly supports [Lightweight Planning](lightweight-planni
 `
   },
   {
-    slug: "fast-feedback",
-    content: `# Fast Feedback
-
-Dust should provide fast feedback loops for developers.
-
-Scripts and tooling should execute quickly so developers can iterate rapidly. Slow feedback discourages frequent validation and leads to larger, riskier changes. Fast feedback enables small, confident steps.
+    slug: "self-diagnosing-tests",
+    content: `# Self-Diagnosing Tests
 
-## Parent Principle
+When a big test fails, it should be self-evident how to diagnose and fix the failure.
 
-- [Make Changes with Confidence](make-changes-with-confidence.md)
+The more moving parts a test has — end-to-end, system, integration — the more critical this becomes. A test that fails with \`expected true, received false\` forces the developer (or agent) to re-run, add logging, and guess. A test that fails with a rich diff showing the actual state versus the expected state turns diagnosis into reading.
 
-## Sub-Principles
+## Anti-patterns
 
-- (none)
-`
-  },
-  {
-    slug: "dependency-injection",
-    content: `# Dependency Injection
+**Boolean flattening** — collapsing a rich value into true/false before asserting:
+\`\`\`javascript
+// Bad: "expected true, received false" — what events arrived?
+expect(events.some(e => e.type === 'check-passed')).toBe(true)
 
-Avoid global mocks. Dependency injection is almost always preferable to testing code that depends directly on globals.
+// Good: shows the actual event types on failure
+expect(events.map(e => e.type)).toContain('check-passed')
+\`\`\`
 
-When code depends on global state or singletons, testing requires mocking those globals—which introduces hidden coupling, complicates test setup, and risks interference between tests. Dependency injection makes dependencies explicit: they're passed in as arguments, making the code's requirements visible and enabling tests to supply controlled implementations.
+**Length-only assertions** — checking count without showing contents:
+\`\`\`javascript
+// Bad: "expected 2, received 0" — what requests were captured?
+expect(requests.length).toBe(2)
 
-This approach improves testability (each test controls its own dependencies), readability (dependencies are declared upfront), and flexibility (swapping implementations doesn't require changing the consuming code). It also makes refactoring safer since dependencies are explicit rather than implicit.
+// Good: shows the actual requests on failure
+expect(requests).toHaveLength(2)  // vitest shows the array
+\`\`\`
 
-## Parent Principle
+**Silent guards** — using \`if\` where an assertion belongs:
+\`\`\`javascript
+// Bad: silently passes when settings is undefined
+if (settings) {
+  expect(JSON.parse(settings).key).toBeDefined()
+}
 
-- [Decoupled Code](decoupled-code.md)
+// Good: fails explicitly if settings is missing
+expect(settings).toBeDefined()
+const parsed = JSON.parse(settings!)
+expect(parsed.key).toBeDefined()
+\`\`\`
 
-## Sub-Principles
+## The test
 
-- (none)
-`
-  },
-  {
-    slug: "reproducible-checks",
-    content: `# Reproducible Checks
+If a test fails, can a developer who has never seen the code identify the problem from the failure output alone — without re-running, adding console.logs, or reading the test source? The closer to "yes", the better.
 
-Every check must produce the same result regardless of who runs it, when, or on what machine. If a check passes for one developer but fails for another, the check is broken.
+## How to evaluate
 
-Concretely, checks should pin their tool versions via the project's dependency manager (e.g. \`devDependencies\`) rather than relying on \`npx\`/\`bunx\` to fetch the latest version at runtime. Unpinned versions introduce non-determinism — a check that passed yesterday may fail today due to a tool upgrade that nobody chose to adopt.
+Work supports this principle when every assertion in a system or integration test would, on failure, reveal the actual state richly enough to guide a fix. Bare boolean checks, length-only assertions, and silent conditional guards are violations.
 
 ## Parent Principle
 
@@ -12176,45 +12805,40 @@ Strategies include separating fast and slow test suites, running slow checks asy
 `
   },
   {
-    slug: "make-changes-with-confidence",
-    content: `# Make Changes with Confidence
+    slug: "agentic-flow-state",
+    content: `# Agentic Flow State
 
-Developers should be able to modify code without fear of breaking existing behavior.
+Flow is the mental state where work becomes effortless - where you're fully immersed, losing track of time, operating at peak performance. Psychologist Mihaly Csikszentmihalyi identified three conditions that create flow: clear goals, immediate feedback, and challenge-skill balance.
 
-Tests, type checking, and other automated verification enable safe refactoring and evolution of the codebase. When changes break something, fast feedback identifies the problem before it spreads. This confidence encourages continuous improvement rather than fragile, stagnant code.
+For AI agents, achieving flow state means staying engaged and productive without interruption. Agents enter flow when they have optimal context, comprehensive guard rails, and minimal friction. Context window optimization ensures agents have exactly what they need without cognitive overload. In-session guard rails prevent agents from straying off course or making mistakes that break their momentum.
+
+Dust's design targets these conditions directly:
+
+- **Clear goals**: Task files and lightweight planning give you a concrete target. You know exactly what you're building next.
+- **Immediate feedback**: Fast feedback loops let you see results quickly. Each change confirms you're on track or shows you what to adjust.
+- **Challenge-skill balance**: Small units of work and agent autonomy keep you in the zone - challenged enough to stay engaged, supported enough to succeed.
+- **Context window efficiency**: Progressive disclosure and artifact summarization ensure agents have the right context without overflow.
+- **Comprehensive guard rails**: Lint rules, type checks, and automated validation catch mistakes before they compound.
+
+Everything dust does serves flow. When agents stay in flow, they produce better work, sustain their momentum, and complete tasks autonomously.
 
 ## Parent Principle
 
-- [Maintainable Codebase](maintainable-codebase.md)
+- (none)
 
 ## Sub-Principles
 
-- [Comprehensive Assertions](comprehensive-assertions.md)
-- [Decoupled Code](decoupled-code.md)
-- [Fast Feedback](fast-feedback.md)
-- [Lint Everything](lint-everything.md)
-- [Readable Test Data](readable-test-data.md)
-- [Reproducible Checks](reproducible-checks.md)
-- [Stop the Line](stop-the-line.md)
-- [Keep Unit Tests Pure](keep-unit-tests-pure.md)
-- [Test Isolation](test-isolation.md)
-- [Self-Diagnosing Tests](self-diagnosing-tests.md)
-- [Unit Test Coverage](unit-test-coverage.md)
+- [Human-AI Collaboration](human-ai-collaboration.md)
+- [Maintainable Codebase](maintainable-codebase.md)
 `
   },
   {
-    slug: "test-isolation",
-    content: `# Test Isolation
-
-Tests should not interfere with one another. Each test must be independently runnable and produce the same result regardless of execution order or which other tests run alongside it.
+    slug: "reproducible-checks",
+    content: `# Reproducible Checks
 
-This means:
-- No shared mutable state between tests
-- No reliance on test execution order
-- No file system or environment pollution
-- Each test sets up its own dependencies
+Every check must produce the same result regardless of who runs it, when, or on what machine. If a check passes for one developer but fails for another, the check is broken.
 
-Test isolation enables parallel execution, makes failures easier to diagnose, and prevents cascading false failures when one test breaks.
+Concretely, checks should pin their tool versions via the project's dependency manager (e.g. \`devDependencies\`) rather than relying on \`npx\`/\`bunx\` to fetch the latest version at runtime. Unpinned versions introduce non-determinism — a check that passed yesterday may fail today due to a tool upgrade that nobody chose to adopt.
 
 ## Parent Principle
 
@@ -12222,70 +12846,52 @@ Test isolation enables parallel execution, makes failures easier to diagnose, an
 
 ## Sub-Principles
 
-- [Environment-Independent Tests](environment-independent-tests.md)
+- (none)
 `
   },
   {
-    slug: "repository-hygiene",
-    content: `# Repository Hygiene
+    slug: "task-first-workflow",
+    content: `# Task-First Workflow
 
-Dust repositories should maintain a clean, organized state with minimal noise.
+Work should be captured as a task before implementation begins, creating traceability between intent and outcome.
 
-This includes proper gitignore configuration to exclude build artifacts, dependencies, editor files, and other generated content from version control. A well-maintained repository makes it easier for both humans and AI to navigate and understand the codebase.
+This discipline ensures that every change has a documented purpose. The commit history shows pairs of "Add task" followed by implementation, making it easy to understand why each change was made. It also prevents scope creep by defining boundaries before work starts.
 
 ## Parent Principle
 
-- [Maintainable Codebase](maintainable-codebase.md)
+- [Lightweight Planning](lightweight-planning.md)
 
 ## Sub-Principles
 
-- [Atomic Commits](atomic-commits.md)
-- [Trunk-Based Development](trunk-based-development.md)
+- (none)
 `
   },
   {
-    slug: "agentic-flow-state",
-    content: `# Agentic Flow State
-
-Flow is the mental state where work becomes effortless - where you're fully immersed, losing track of time, operating at peak performance. Psychologist Mihaly Csikszentmihalyi identified three conditions that create flow: clear goals, immediate feedback, and challenge-skill balance.
+    slug: "ideal-agent-developer-experience",
+    content: `# Ideal Agent Developer Experience
 
-For AI agents, achieving flow state means staying engaged and productive without interruption. Agents enter flow when they have optimal context, comprehensive guard rails, and minimal friction. Context window optimization ensures agents have exactly what they need without cognitive overload. In-session guard rails prevent agents from straying off course or making mistakes that break their momentum.
+The agent is the developer. The human is the CEO. Dust is the PM.
 
-Dust's design targets these conditions directly:
+With today's AI coding assistants, the human is stuck in a tight loop with agents — constantly directing, reviewing, and course-correcting. Dust is designed to relieve humans from this tight loop. Like an assistant to a CEO, dust predominantly brings fully-researched questions and well-prepared work to the human, rather than expecting the human to drive every decision. The human checks in less frequently, and when they do, they make high-leverage strategic calls rather than micromanaging implementation.
 
-- **Clear goals**: Task files and lightweight planning give you a concrete target. You know exactly what you're building next.
-- **Immediate feedback**: Fast feedback loops let you see results quickly. Each change confirms you're on track or shows you what to adjust.
-- **Challenge-skill balance**: Small units of work and agent autonomy keep you in the zone - challenged enough to stay engaged, supported enough to succeed.
-- **Context window efficiency**: Progressive disclosure and artifact summarization ensure agents have the right context without overflow.
-- **Comprehensive guard rails**: Lint rules, type checks, and automated validation catch mistakes before they compound.
+For this to work, the agent's development environment must be excellent. The agent reads the code, writes changes, runs the checks, and iterates until the task is done. Everything about the codebase and its tooling either helps or hinders that process. Comprehensive tests are the agent's only way to verify correctness. Fast feedback loops are the agent's iteration speed. Structured logs are the agent's eyes into runtime behaviour. Small, well-organised files are what fit in the agent's context window. Exploratory and debugging tools are how the agent navigates and diagnoses without trial and error.
 
-Everything dust does serves flow. When agents stay in flow, they produce better work, sustain their momentum, and complete tasks autonomously.
+Each sub-principle represents a different aspect of the ideal agent developer setup. The better these are, the less the human needs to be in the loop.
 
 ## Parent Principle
 
-- (none)
-
-## Sub-Principles
-
 - [Human-AI Collaboration](human-ai-collaboration.md)
-- [Maintainable Codebase](maintainable-codebase.md)
-`
-  },
-  {
-    slug: "stop-the-line",
-    content: `# Stop the Line
-
-Any worker — human or agent — should halt and fix a problem the moment they detect it, rather than letting defects propagate downstream.
-
-Originating from the Toyota production system, "Stop the Line" empowers every participant to pause work immediately upon identifying a defect, failing check, or safety hazard. Problems are cheaper to fix at their source than after they've compounded through later stages. In the context of dust, this means agents and humans alike should treat broken checks, test failures, and lint errors as blockers that demand immediate attention — not warnings to be deferred.
-
-## Parent Principle
-
-- [Make Changes with Confidence](make-changes-with-confidence.md)
 
 ## Sub-Principles
 
-- (none)
+- [Comprehensive Test Coverage](comprehensive-test-coverage.md)
+- [Fast Feedback Loops](fast-feedback-loops.md)
+- [Slow Feedback Coping](slow-feedback-coping.md)
+- [Development Traceability](development-traceability.md)
+- [Context-Optimised Code](context-optimised-code.md)
+- [Exploratory Tooling](exploratory-tooling.md)
+- [Debugging Tooling](debugging-tooling.md)
+- [Self-Contained Repository](self-contained-repository.md)
 `
   },
   {
@@ -12312,21 +12918,26 @@ Internal
 `
   },
   {
-    slug: "naming-matters",
-    content: `# Naming Matters
+    slug: "agent-autonomy",
+    content: `# Agent Autonomy
 
-Good naming reduces waste by eliminating confusion and making code self-documenting.
+Dust exists to enable AI agents to produce work autonomously.
 
-Poor names cause rework, bugs, and communication overhead. When names don't clearly convey meaning, developers waste time deciphering code, misunderstand intentions, and introduce defects. Well-chosen names serve as documentation that never goes stale, reducing the need for explanatory comments and enabling both humans and AI agents to navigate the codebase efficiently.
+With sufficient planning and small enough units, this works much better in practice.
 
 ## Parent Principle
 
-- [Maintainable Codebase](maintainable-codebase.md)
+- [Human-AI Collaboration](human-ai-collaboration.md)
 
 ## Sub-Principles
 
-- [Consistent Naming](consistent-naming.md)
-- [Clarity Over Brevity](clarity-over-brevity.md)
+- [Actionable Errors](actionable-errors.md)
+- [Batteries Included](batteries-included.md)
+- [Agent-Agnostic Design](agent-agnostic-design.md)
+- [Agent Context Inference](agent-context-inference.md)
+- [Agent-Specific Enhancement](agent-specific-enhancement.md)
+- [Context Window Efficiency](context-window-efficiency.md)
+- [Small Units](small-units.md)
 `
   },
   {
@@ -12353,33 +12964,14 @@ Still use mocks selectively—mainly to assert something is called (e.g., teleme
 `
   },
   {
-    slug: "functional-core-imperative-shell",
-    content: `# Functional Core, Imperative Shell
-
-Separate code into a pure "functional core" and a thin "imperative shell." The core takes values in and returns values out, with no side effects. The shell handles I/O and wires things together.
-
-Purely functional code makes some things easier to understand: because values don't change, you can call functions and know that only their return value matters—they don't change anything outside themselves.
-
-The functional core contains business logic as pure functions that take values and return values. The imperative shell sits at the boundary, reading input, calling into the core, and performing side effects with the results. This keeps the majority of code easy to test (no mocks or stubs needed for pure functions) and makes the I/O surface area small and explicit.
-
-## Parent Principle
-
-- [Decoupled Code](decoupled-code.md)
-
-## Sub-Principles
-
-- (none)
-`
-  },
-  {
-    slug: "development-traceability",
-    content: `# Development Traceability
+    slug: "debugging-tooling",
+    content: `# Debugging Tooling
 
-Structured logging and tracing help agents understand system behaviour without resorting to ad-hoc testing cycles.
+Agents need effective tools for diagnosing and fixing issues without manual intervention.
 
-When something goes wrong, agents often resort to adding temporary log statements, running the code, reading the output, and repeating — a slow and wasteful debugging loop. Good traceability means the system already records what happened and why, through structured logs, trace IDs, and observable state. This lets agents diagnose issues by reading existing output rather than generating new experiments.
+Traditional debugging relies on breakpoints, stepping through code, and interactive inspection — techniques that work well for humans but poorly for agents. Agents need debugging tools that produce readable, structured output: stack traces with context, diff-friendly error messages, reproducible test cases, and diagnostic commands that can be run non-interactively.
 
-Dust should encourage projects to adopt structured logging, promote traceability as a first-class concern, and provide tools that surface relevant trace information when agents need it.
+Dust should help projects adopt agent-friendly debugging practices: structured error output, diagnostic scripts, snapshot testing for complex state, and tools that turn vague symptoms into specific, actionable information.
 
 ## Applicability
 
@@ -12395,45 +12987,16 @@ Internal
 `
   },
   {
-    slug: "keep-unit-tests-pure",
-    content: `# Keep Unit Tests Pure
-
-Unit tests (those run very frequently as part of a tight feedback loop) should be pure and side-effect free. A test is **not** a unit test if it:
-
-- Accesses a database
-- Communicates over a network
-- Touches the file system
-- Cannot run concurrently with other tests
-- Requires special environment setup
-
-"Unit tests" here means tests run frequently during development — not system tests, which intentionally exercise the full stack including I/O. Pure unit tests exercise only business logic, not infrastructure.
-
-The value of pure unit tests is that they are fast, deterministic, and isolate business logic from infrastructure concerns. When unit tests pass but integration or system tests fail, developers can immediately narrow the problem to the boundary layer — a diagnostic "binary chop" that accelerates debugging.
-
-## Migration Guidance
-
-Where existing tests are impure (e.g. they spawn processes, write temporary files, or make network calls), prefer converting them to use in-memory alternatives — stubs, fakes, or dependency-injected doubles — rather than leaving them as-is. Opportunistic migration is fine; a big-bang rewrite is not required.
-
-## Parent Principle
-
-- [Make Changes with Confidence](make-changes-with-confidence.md)
-
-## Sub-Principles
-
-- (none)
-`
-  },
-  {
-    slug: "co-located-tests",
-    content: `# Co-located Tests
+    slug: "consistent-naming",
+    content: `# Consistent Naming
 
-Test files should live next to the code they test.
+Names should follow established conventions within each category to reduce cognitive load.
 
-When tests are co-located with their source files, developers can immediately see what's tested and what isn't. Finding the test for a module becomes trivial—it's right there in the same directory. This proximity encourages writing tests as part of the development flow rather than as an afterthought, and makes it natural to update tests when modifying code.
+Principles use Title Case. File names use kebab-case. Commands use lowercase with hyphens. When naming conventions exist, follow them. When they don't, establish one and apply it consistently. Inconsistent naming creates friction for both humans and AI agents trying to predict or recall identifiers.
 
 ## Parent Principle
 
-- [Intuitive Directory Structure](intuitive-directory-structure.md)
+- [Naming Matters](naming-matters.md)
 
 ## Sub-Principles
 
@@ -12441,180 +13004,156 @@ When tests are co-located with their source files, developers can immediately se
 `
   },
   {
-    slug: "human-ai-collaboration",
-    content: `# Human-AI Collaboration
+    slug: "lightweight-planning",
+    content: `# Lightweight Planning
 
-Dust exists to enable effective collaboration between humans and AI agents on complex projects.
+Dust aims to be a minimal, low-overhead planning system that stays relevant over time.
 
-The human is the CEO — they set direction, make strategic decisions, and check in when it matters. Dust is the PM — it manages the work, prepares context, and brings fully-researched questions to the human rather than expecting them to drive every detail. Agents are the developers — they read code, write changes, and iterate autonomously.
+Planning artifacts are simple markdown files that live alongside code. Ideas are intentionally vague until implementation is imminent. Tasks are small and completable in single commits. Facts document current reality rather than aspirational states.
 
-Today's AI coding tools keep humans in a tight loop with agents. Dust is designed to loosen that loop, so humans spend less time directing and more time deciding.
+The system avoids the staleness problem by deferring detail until the last responsible moment and deleting completed work rather than archiving it.
 
 ## Parent Principle
 
-- [Agentic Flow State](agentic-flow-state.md)
+- [Human-AI Collaboration](human-ai-collaboration.md)
 
 ## Sub-Principles
 
-- [Agent Autonomy](agent-autonomy.md)
-- [Easy Adoption](easy-adoption.md)
-- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
-- [Lightweight Planning](lightweight-planning.md)
+- [Task-First Workflow](task-first-workflow.md)
+- [Some Big Design Up Front](some-big-design-up-front.md)
 `
   },
   {
-    slug: "vcs-independence",
-    content: `# VCS Independence
+    slug: "easy-adoption",
+    content: `# Easy Adoption
 
-Dust should work independently of any specific version control system.
+Dust should be trivially easy to adopt in any repository.
 
-While git is common, dust's core functionality should not require git. This enables use in repositories using other VCS (Mercurial, SVN, Perforce) or in non-VCS workflows.
+Getting started with Dust should require minimal friction. A developer should be able to bootstrap Dust in their repository with a single command, without needing to install dependencies, configure build tools, or understand the internals.
+
+This lowers the barrier to entry and encourages experimentation.
 
 ## Parent Principle
 
-- [Easy Adoption](easy-adoption.md)
+- [Human-AI Collaboration](human-ai-collaboration.md)
 
 ## Sub-Principles
 
-- (none)
+- [Cross-Platform Compatibility](cross-platform-compatibility.md)
+- [Unsurprising UX](unsurprising-ux.md)
+- [VCS Independence](vcs-independence.md)
 `
   },
   {
-    slug: "environment-independent-tests",
-    content: `# Environment-Independent Tests
-
-Tests must produce the same result regardless of where they run. A test that passes locally but fails in CI (or vice versa) is a broken test.
+    slug: "intuitive-directory-structure",
+    content: `# Intuitive Directory Structure
 
-Concretely, tests should never depend on:
-- Ambient environment variables (e.g. \`CLAUDECODE\`, \`CI\`, \`HOME\`)
-- The current working directory or filesystem layout of the host machine
-- Network availability or external services
-- The identity of the user or agent running the tests
+Code should be organized around related concerns in clearly named directories.
 
-When a function's behavior depends on environment variables, the test must explicitly control those variables (via \`stubEnv\`, dependency injection, or passing an \`env\` parameter) rather than relying on whatever happens to be set in the current shell.
+When files that serve similar purposes are grouped together, the codebase becomes easier to navigate and understand. A developer looking for "commands" should find them in a \`commands\` directory. Utilities should live with utilities. This organization reduces cognitive load and makes the project structure self-documenting.
 
 ## Parent Principle
 
-- [Test Isolation](test-isolation.md)
+- [Maintainable Codebase](maintainable-codebase.md)
 
 ## Sub-Principles
 
-- (none)
+- [Co-located Tests](co-located-tests.md)
 `
   },
   {
-    slug: "debugging-tooling",
-    content: `# Debugging Tooling
-
-Agents need effective tools for diagnosing and fixing issues without manual intervention.
-
-Traditional debugging relies on breakpoints, stepping through code, and interactive inspection — techniques that work well for humans but poorly for agents. Agents need debugging tools that produce readable, structured output: stack traces with context, diff-friendly error messages, reproducible test cases, and diagnostic commands that can be run non-interactively.
+    slug: "lint-everything",
+    content: `# Lint Everything
 
-Dust should help projects adopt agent-friendly debugging practices: structured error output, diagnostic scripts, snapshot testing for complex state, and tools that turn vague symptoms into specific, actionable information.
+Prefer static analysis over runtime checks. Every error caught by a linter is an error that never reaches tests, and every error caught by tests is an error that never reaches production.
 
-## Applicability
+Lint markdown, lint types, lint formatting. If it can be checked statically, check it. Linters are fast, deterministic, and catch entire categories of bugs before code even runs.
 
-Internal
+This project lints:
+- TypeScript (type checking and style)
+- Markdown (broken links, required sections)
+- Task files (structure validation)
+- Principle hierarchy (parent/child consistency)
 
 ## Parent Principle
 
-- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+- [Make Changes with Confidence](make-changes-with-confidence.md)
 
 ## Sub-Principles
 
-- (none)
+(none)
 `
   },
   {
-    slug: "atomic-commits",
-    content: `# Atomic Commits
+    slug: "progressive-disclosure",
+    content: `# Progressive Disclosure
 
-Each commit should tell a complete story, bundling implementation changes with their corresponding documentation updates.
+Dust should reveal details progressively as a way of achieving context window efficiency.
 
-When a task is completed, the commit deletes the task file, updates relevant facts to reflect the new reality, and removes any ideas that have been realized. This discipline ensures that any point in the commit history represents a coherent, self-documenting state of the project.
+Not all information is needed at once. A task list showing just titles is sufficient for choosing what to work on. Full task details are only needed when actively implementing. Linked principles and facts can be followed when deeper context is required.
 
-Clean commit history is essential because archaeology depends on it. Future humans and AI agents will traverse history to understand why decisions were made and how the system evolved.
+This layered approach keeps initial reads lightweight while preserving access to complete information when needed.
 
 ## Parent Principle
 
-- [Repository Hygiene](repository-hygiene.md)
+- [Context Window Efficiency](context-window-efficiency.md)
 
 ## Sub-Principles
 
-- [Traceable Decisions](traceable-decisions.md)
+- (none)
 `
   },
   {
-    slug: "trunk-based-development",
-    content: `# Trunk-Based Development
-
-Dust is designed to support a non-branching workflow where developers commit directly to a single main branch.
-
-In trunk-based development, teams collaborate on code in one primary branch rather than maintaining multiple long-lived feature branches. This eliminates merge conflicts, enables continuous integration, and keeps the codebase continuously releasable.
+    slug: "context-optimised-code",
+    content: `# Context-Optimised Code
 
-The \`dust loop claude\` command embodies this philosophy: agents pull from main, implement a task, and push directly back to main. There are no feature branches, no pull requests, no merge queues. Each commit is atomic and complete.
+Code should be structured so that agents can understand and modify it within their context window constraints.
 
-This approach scales through discipline rather than isolation. Feature flags and incremental changes replace long-running branches. The repository history becomes a linear sequence of working states.
+Large files, deeply nested abstractions, and sprawling dependency chains all work against agents. A 3,000-line file cannot be fully loaded into context. A function that requires understanding six levels of indirection demands more context than one that is self-contained. Context-optimised code favours small files, shallow abstractions, explicit dependencies, and co-located related logic.
 
-See: https://trunkbaseddevelopment.com/
+Dust should help projects identify files that are too large, modules that are too tangled, and patterns that make agent comprehension harder than it needs to be. This is not just about file size — it is about ensuring that the unit of code an agent needs to understand fits comfortably within the window available.
 
 ## Parent Principle
 
-- [Repository Hygiene](repository-hygiene.md)
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
 
 ## Sub-Principles
 
-(none)
+- (none)
 `
   },
   {
-    slug: "comprehensive-assertions",
-    content: `# Comprehensive Assertions
-
-Assert the whole, not the parts.
-
-When you break a complex object into many small assertions, a failure tells you *one thing that's wrong*. When you assert against the whole expected value, the diff tells you *what actually happened versus what you expected* — the full picture, in one glance.
+    slug: "some-big-design-up-front",
+    content: `# Some Big Design Up Front
 
-Small assertions are like yes/no questions to a witness. A whole-object assertion is like asking "tell me what you saw."
+AI agents lower the cost of architectural exploration, making heavier upfront investment rational during the idea phase.
 
-## In practice
+Agile's rejection of "big design up front" (BDUF) was largely economic: detailed architecture was expensive to produce and often wrong. AI agents change that equation — they can explore multiple variants, prototype them, and measure trade-offs cheaply. When evaluating alternatives costs less, the expected value of avoiding large structural mistakes increases.
 
-Collapse multiple partial assertions into one comprehensive assertion:
+This doesn't mean returning to traditional BDUF. Uncertainty about future requirements still limits what prediction can achieve. The insight is that the optimal amount of upfront work has shifted, not that prediction became reliable.
 
-\`\`\`javascript
-// Fragmented — each failure is a narrow keyhole
-expect(result.name).toBe("Alice");
-expect(result.age).toBe(30);
-expect(result.role).toBe("admin");
+The model is hybrid: thorough AI-assisted exploration during ideas, followed by straightforward execution during tasks. "Lightweight" refers to task-level planning, not idea-level exploration. Invest heavily in understanding alternatives during the idea phase, then decompose into atomic tasks once the direction is clear.
 
-// Whole — a failure diff tells the full story
-expect(result).toEqual({
-  name: "Alice",
-  age: 30,
-  role: "admin",
-});
-\`\`\`
+## Convergence Criteria
 
-If \`role\` is \`"user"\` and \`age\` is \`29\`, the fragmented version stops at the first failure. The whole-object assertion shows both discrepancies at once, in context.
+Exploration should continue until clear trade-offs are identified and the chosen approach can be articulated against alternatives. This is convergence-based, not time-boxed — simple ideas converge quickly, complex architectural decisions require more exploration.
 
-The same applies to arrays:
+When exploration feels "done":
 
-\`\`\`javascript
-// Avoid: partial assertions that hide the actual state
-expect(array).toContain('apples')
-expect(array).toContain('oranges')
+- Multiple approaches have been considered
+- Trade-offs between approaches are understood
+- The chosen direction has clear justification
+- Remaining uncertainty is about requirements, not design
 
-// Prefer: one assertion that reveals the full picture on failure
-expect(array).toEqual(['apples', 'oranges'])
-\`\`\`
+If a task requires significant design decisions during execution, it wasn't ready to be a task.
 
-## How to evaluate
+## Documenting Alternatives
 
-Work supports this principle when test failures tell a rich story — showing the complete actual value alongside the complete expected value, so the reader can understand what happened without re-running anything.
+Ideas should document the alternatives considered and why they were ruled out. This creates a decision log that helps future agents and humans understand context. Include alternatives in the idea body or Open Questions sections.
 
 ## Parent Principle
 
-- [Make Changes with Confidence](make-changes-with-confidence.md)
+- [Lightweight Planning](lightweight-planning.md)
 
 ## Sub-Principles
 
@@ -12622,22 +13161,16 @@ Work supports this principle when test failures tell a rich story — showing th
 `
   },
   {
-    slug: "cross-platform-compatibility",
-    content: `# Cross-Platform Compatibility
-
-Dust should work consistently across operating systems: Linux, macOS, and Windows.
+    slug: "traceable-decisions",
+    content: `# Traceable Decisions
 
-This means:
-- Avoiding platform-specific shell commands or syntax
-- Using cross-platform path handling
-- Testing on multiple platforms when possible
-- Documenting any platform-specific limitations
+The commit history should explain why changes were made, not just what changed.
 
-Cross-platform support broadens adoption and ensures teams with mixed environments can collaborate effectively.
+Commit messages should capture intent and context that would otherwise be lost. Future maintainers (human or AI) will traverse history to understand the reasoning behind decisions. A commit that says "Fix bug" is less valuable than one that explains what was broken and why the fix is correct.
 
 ## Parent Principle
 
-- [Easy Adoption](easy-adoption.md)
+- [Atomic Commits](atomic-commits.md)
 
 ## Sub-Principles
 
@@ -12645,22 +13178,16 @@ Cross-platform support broadens adoption and ensures teams with mixed environmen
 `
   },
   {
-    slug: "exploratory-tooling",
-    content: `# Exploratory Tooling
-
-Agents need tools to efficiently explore and understand unfamiliar codebases.
-
-When an agent encounters a new codebase — or an unfamiliar corner of a familiar one — it needs to quickly build a mental model: what exists, how it fits together, and where to make changes. Without good exploratory tools, agents waste context on trial-and-error searches, reading irrelevant files, and forming incorrect assumptions.
-
-Dust should promote and integrate tools that help agents explore: dependency graphs, module overviews, search utilities tuned for code navigation, and summaries of project structure. The goal is to make the "orientation" phase of any task as short and reliable as possible.
+    slug: "fast-feedback",
+    content: `# Fast Feedback
 
-## Applicability
+Dust should provide fast feedback loops for developers.
 
-Internal
+Scripts and tooling should execute quickly so developers can iterate rapidly. Slow feedback discourages frequent validation and leads to larger, riskier changes. Fast feedback enables small, confident steps.
 
 ## Parent Principle
 
-- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+- [Make Changes with Confidence](make-changes-with-confidence.md)
 
 ## Sub-Principles
 
@@ -12668,50 +13195,63 @@ Internal
 `
   },
   {
-    slug: "reasonably-dry",
-    content: `# Reasonably DRY
+    slug: "decoupled-code",
+    content: `# Decoupled Code
 
-Don't repeat yourself is a good principle, but don't overdo it.
+Code should be organized into independent units with explicit dependencies.
 
-Extracting shared code too eagerly can create tight coupling, obscure intent, and make changes harder. When two pieces of code look similar but serve different purposes or are likely to evolve independently, duplication is the better choice. The cost of a wrong abstraction is higher than the cost of a little repetition. Extract shared code when the duplication is truly about the same concept and has proven stable, not just because two things happen to look alike right now.
+Decoupled code is easier to test, understand, and modify. Dependencies are passed in rather than hard-coded, enabling units to be tested in isolation and composed flexibly. This reduces the blast radius of changes and makes the system more maintainable.
 
 ## Parent Principle
 
-- [Maintainable Codebase](maintainable-codebase.md)
+- [Make Changes with Confidence](make-changes-with-confidence.md)
 
 ## Sub-Principles
 
-- (none)
+- [Dependency Injection](dependency-injection.md)
+- [Stubs Over Mocks](stubs-over-mocks.md)
+- [Functional Core, Imperative Shell](functional-core-imperative-shell.md)
+- [Design for Testability](design-for-testability.md)
 `
   },
   {
-    slug: "runtime-agnostic-tests",
-    content: `# Runtime Agnostic Tests
+    slug: "make-changes-with-confidence",
+    content: `# Make Changes with Confidence
 
-Dust's test suite should work across JavaScript runtimes.
+Developers should be able to modify code without fear of breaking existing behavior.
 
-Tests should use standard JavaScript testing patterns that work across Node.js, Bun, and other runtimes. Avoiding runtime-specific test APIs ensures the project can leverage different runtimes' advantages while maintaining broad compatibility.
+Tests, type checking, and other automated verification enable safe refactoring and evolution of the codebase. When changes break something, fast feedback identifies the problem before it spreads. This confidence encourages continuous improvement rather than fragile, stagnant code.
 
 ## Parent Principle
 
-- [Minimal Dependencies](minimal-dependencies.md)
+- [Maintainable Codebase](maintainable-codebase.md)
 
 ## Sub-Principles
 
-- (none)
+- [Comprehensive Assertions](comprehensive-assertions.md)
+- [Decoupled Code](decoupled-code.md)
+- [Fast Feedback](fast-feedback.md)
+- [Lint Everything](lint-everything.md)
+- [Readable Test Data](readable-test-data.md)
+- [Reproducible Checks](reproducible-checks.md)
+- [Stop the Line](stop-the-line.md)
+- [Keep Unit Tests Pure](keep-unit-tests-pure.md)
+- [Test Isolation](test-isolation.md)
+- [Self-Diagnosing Tests](self-diagnosing-tests.md)
+- [Unit Test Coverage](unit-test-coverage.md)
 `
   },
   {
-    slug: "task-first-workflow",
-    content: `# Task-First Workflow
+    slug: "clarity-over-brevity",
+    content: `# Clarity Over Brevity
 
-Work should be captured as a task before implementation begins, creating traceability between intent and outcome.
+Names should be descriptive and self-documenting, even if longer.
 
-This discipline ensures that every change has a documented purpose. The commit history shows pairs of "Add task" followed by implementation, making it easy to understand why each change was made. It also prevents scope creep by defining boundaries before work starts.
+Abbreviated names like \`ctx\`, \`deps\`, \`fs\`, or \`args\` save a few keystrokes but obscure meaning. Full names like \`context\`, \`dependencies\`, \`fileSystem\`, and \`arguments\` make code immediately understandable without requiring readers to decode conventions. This is especially valuable when AI agents or new contributors read the codebase for the first time.
 
 ## Parent Principle
 
-- [Lightweight Planning](lightweight-planning.md)
+- [Naming Matters](naming-matters.md)
 
 ## Sub-Principles
 
@@ -12719,58 +13259,76 @@ This discipline ensures that every change has a documented purpose. The commit h
 `
   },
   {
-    slug: "agent-autonomy",
-    content: `# Agent Autonomy
+    slug: "agent-agnostic-design",
+    content: `# Agent-Agnostic Design
 
-Dust exists to enable AI agents to produce work autonomously.
+Dust should work with multiple agents without favoring one.
 
-With sufficient planning and small enough units, this works much better in practice.
+Rather than implementing agents, Dust generates prompts and context that can be passed to any capable agent. This keeps Dust lightweight and allows teams to use whatever agent tooling they prefer.
+
+Dust may have built-in support for invoking popular agents (Claude, Aider, Codex, etc.), but the choice of agent should always be made by the user at runtime - never hard-coded into repository configuration.
+
+Note: Supporting multiple agents directly contributes to [Easy Adoption](easy-adoption.md), since teams can use their preferred agent tools without being locked into a specific platform.
+
+## Applicability
+
+Internal
 
 ## Parent Principle
 
-- [Human-AI Collaboration](human-ai-collaboration.md)
+- [Agent Autonomy](agent-autonomy.md)
 
 ## Sub-Principles
 
-- [Actionable Errors](actionable-errors.md)
-- [Batteries Included](batteries-included.md)
-- [Agent-Agnostic Design](agent-agnostic-design.md)
-- [Agent Context Inference](agent-context-inference.md)
-- [Agent-Specific Enhancement](agent-specific-enhancement.md)
-- [Context Window Efficiency](context-window-efficiency.md)
-- [Small Units](small-units.md)
+- (none)
 `
   },
   {
-    slug: "clarity-over-brevity",
-    content: `# Clarity Over Brevity
+    slug: "readable-test-data",
+    content: `# Readable Test Data
 
-Names should be descriptive and self-documenting, even if longer.
+Test data setup should use natural structures that mirror what they represent.
 
-Abbreviated names like \`ctx\`, \`deps\`, \`fs\`, or \`args\` save a few keystrokes but obscure meaning. Full names like \`context\`, \`dependencies\`, \`fileSystem\`, and \`arguments\` make code immediately understandable without requiring readers to decode conventions. This is especially valuable when AI agents or new contributors read the codebase for the first time.
+## Why it matters
 
-## Parent Principle
+When test data is easy to read, tests become self-documenting. A file system hierarchy expressed as a nested object immediately conveys structure, while a flat Map with path strings requires mental parsing to understand the relationships.
 
-- [Naming Matters](naming-matters.md)
+## In practice
 
-## Sub-Principles
+Prefer literal structures that visually match the domain:
 
-- (none)
-`
-  },
-  {
-    slug: "fast-feedback-loops",
-    content: `# Fast Feedback Loops
+\`\`\`javascript
+// Avoid: flat paths that obscure hierarchy
+const fs = createFileSystemEmulator({
+  files: new Map([['/project/.dust/principles/my-goal.md', '# My Goal']]),
+  existingPaths: new Set(['/project/.dust/ideas']),
+})
 
-The primary feedback loop — write code, run checks, see results — should be as fast as possible.
+// Prefer: nested object that mirrors file system structure
+const fs = createFileSystemEmulator({
+  project: {
+    '.dust': {
+      principles: {
+        'my-goal.md': '# My Goal'
+      },
+      ideas: {}
+    }
+  }
+})
+\`\`\`
+
+The nested form:
+- Shows parent-child relationships through indentation
+- Makes empty directories explicit with empty objects
+- Requires no mental path concatenation to understand structure
 
-Fast feedback is the foundation of productive development, for both humans and agents. When tests, linters, and type checks run in seconds rather than minutes, developers iterate more frequently and catch problems earlier. Agents especially benefit because they operate in tight loops of change-and-verify; slow feedback wastes tokens and context window space on waiting rather than working.
+## How to evaluate
 
-Dust should help projects measure the speed of their feedback loops, identify bottlenecks, and keep them fast as the codebase grows. This includes promoting practices like unit tests over integration tests for speed, incremental compilation, and check parallelisation.
+Work supports this principle when test setup data uses structures that visually resemble what they represent, reducing cognitive load for readers.
 
 ## Parent Principle
 
-- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+- [Make Changes with Confidence](make-changes-with-confidence.md)
 
 ## Sub-Principles
 
@@ -12778,14 +13336,12 @@ Dust should help projects measure the speed of their feedback loops, identify bo
 `
   },
   {
-    slug: "make-the-change-easy",
-    content: `# Make the Change Easy
-
-For each desired change, make the change easy, then make the easy change.
+    slug: "reasonably-dry",
+    content: `# Reasonably DRY
 
-This principle, articulated by Kent Beck, recognizes that the hardest part of a change is often not the change itself but the state of the code receiving it. When code resists a change, the right response is to first refactor until the change becomes straightforward, and only then make it. The warning - "this may be hard" - acknowledges that preparing the ground takes real effort, but the result is a change that fits naturally rather than one forced in against the grain.
+Don't repeat yourself is a good principle, but don't overdo it.
 
-Work that supports this principle includes refactoring before feature work, improving abstractions that make a category of changes simpler, and resisting the urge to bolt changes onto code that isn't ready for them.
+Extracting shared code too eagerly can create tight coupling, obscure intent, and make changes harder. When two pieces of code look similar but serve different purposes or are likely to evolve independently, duplication is the better choice. The cost of a wrong abstraction is higher than the cost of a little repetition. Extract shared code when the duplication is truly about the same concept and has proven stable, not just because two things happen to look alike right now.
 
 ## Parent Principle
 
@@ -12797,20 +13353,21 @@ Work that supports this principle includes refactoring before feature work, impr
 `
   },
   {
-    slug: "self-contained-repository",
-    content: `# Self-Contained Repository
-
-Where possible, developers and agents should have everything they need to be productive, within the repository.
+    slug: "actionable-errors",
+    content: `# Actionable Errors
 
-No third-party tools should be required beyond those that can be installed with a single command defined in the repository. Setup instructions, scripts, configuration, and dependencies should all live in version control so that cloning the repo and running a single install command is sufficient to start working. This eliminates onboarding friction, reduces "works on my machine" issues, and is especially important for agents — who cannot browse the web to find missing tools or ask colleagues how to set things up.
+Error messages should tell you what to do next, not just what went wrong.
 
-## Applicability
+When something fails, the message should provide:
+- A clear description of the problem
+- Specific guidance on how to fix it
+- Context needed to take the next step
 
-Internal
+This is especially important for AI agents, who need concrete instructions to recover autonomously. A good error message turns a dead end into a signpost.
 
 ## Parent Principle
 
-- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+- [Agent Autonomy](agent-autonomy.md)
 
 ## Sub-Principles
 
@@ -12818,16 +13375,18 @@ Internal
 `
   },
   {
-    slug: "traceable-decisions",
-    content: `# Traceable Decisions
+    slug: "make-the-change-easy",
+    content: `# Make the Change Easy
 
-The commit history should explain why changes were made, not just what changed.
+For each desired change, make the change easy, then make the easy change.
 
-Commit messages should capture intent and context that would otherwise be lost. Future maintainers (human or AI) will traverse history to understand the reasoning behind decisions. A commit that says "Fix bug" is less valuable than one that explains what was broken and why the fix is correct.
+This principle, articulated by Kent Beck, recognizes that the hardest part of a change is often not the change itself but the state of the code receiving it. When code resists a change, the right response is to first refactor until the change becomes straightforward, and only then make it. The warning - "this may be hard" - acknowledges that preparing the ground takes real effort, but the result is a change that fits naturally rather than one forced in against the grain.
+
+Work that supports this principle includes refactoring before feature work, improving abstractions that make a category of changes simpler, and resisting the urge to bolt changes onto code that isn't ready for them.
 
 ## Parent Principle
 
-- [Atomic Commits](atomic-commits.md)
+- [Maintainable Codebase](maintainable-codebase.md)
 
 ## Sub-Principles
 
@@ -12835,16 +13394,18 @@ Commit messages should capture intent and context that would otherwise be lost.
 `
   },
   {
-    slug: "unit-test-coverage",
-    content: `# Unit Test Coverage
+    slug: "dependency-injection",
+    content: `# Dependency Injection
 
-Complete unit test coverage ensures low-level tests give users direct feedback as they change the code.
+Avoid global mocks. Dependency injection is almost always preferable to testing code that depends directly on globals.
 
-Excluding system tests from coverage reporting focuses attention on unit tests - the tests that provide the fastest, most specific feedback. When coverage tools only measure unit tests, developers can quickly identify which parts of the codebase lack fine-grained test protection.
+When code depends on global state or singletons, testing requires mocking those globals—which introduces hidden coupling, complicates test setup, and risks interference between tests. Dependency injection makes dependencies explicit: they're passed in as arguments, making the code's requirements visible and enabling tests to supply controlled implementations.
+
+This approach improves testability (each test controls its own dependencies), readability (dependencies are declared upfront), and flexibility (swapping implementations doesn't require changing the consuming code). It also makes refactoring safer since dependencies are explicit rather than implicit.
 
 ## Parent Principle
 
-- [Make Changes with Confidence](make-changes-with-confidence.md)
+- [Decoupled Code](decoupled-code.md)
 
 ## Sub-Principles
 
@@ -12852,84 +13413,53 @@ Excluding system tests from coverage reporting focuses attention on unit tests -
 `
   },
   {
-    slug: "decoupled-code",
-    content: `# Decoupled Code
+    slug: "repository-hygiene",
+    content: `# Repository Hygiene
 
-Code should be organized into independent units with explicit dependencies.
+Dust repositories should maintain a clean, organized state with minimal noise.
 
-Decoupled code is easier to test, understand, and modify. Dependencies are passed in rather than hard-coded, enabling units to be tested in isolation and composed flexibly. This reduces the blast radius of changes and makes the system more maintainable.
+This includes proper gitignore configuration to exclude build artifacts, dependencies, editor files, and other generated content from version control. A well-maintained repository makes it easier for both humans and AI to navigate and understand the codebase.
 
 ## Parent Principle
 
-- [Make Changes with Confidence](make-changes-with-confidence.md)
+- [Maintainable Codebase](maintainable-codebase.md)
 
 ## Sub-Principles
 
-- [Dependency Injection](dependency-injection.md)
-- [Stubs Over Mocks](stubs-over-mocks.md)
-- [Functional Core, Imperative Shell](functional-core-imperative-shell.md)
-- [Design for Testability](design-for-testability.md)
+- [Atomic Commits](atomic-commits.md)
+- [Trunk-Based Development](trunk-based-development.md)
 `
   },
   {
-    slug: "lint-everything",
-    content: `# Lint Everything
-
-Prefer static analysis over runtime checks. Every error caught by a linter is an error that never reaches tests, and every error caught by tests is an error that never reaches production.
-
-Lint markdown, lint types, lint formatting. If it can be checked statically, check it. Linters are fast, deterministic, and catch entire categories of bugs before code even runs.
-
-This project lints:
-- TypeScript (type checking and style)
-- Markdown (broken links, required sections)
-- Task files (structure validation)
-- Principle hierarchy (parent/child consistency)
-
-## Parent Principle
+    slug: "batteries-included",
+    content: `# Batteries Included
 
-- [Make Changes with Confidence](make-changes-with-confidence.md)
+Dust should provide everything that is required (within reason) for an agent to be productive in an arbitrary codebase.
 
-## Sub-Principles
+An agent working autonomously should not be blocked because a tool or configuration is missing. For example, dust should ship custom lint rules for different linters, even though those linters are not dependencies of dust itself. If an agent needs a capability to do its job well in a typical codebase, dust should provide it out of the box.
 
-(none)
-`
-  },
-  {
-    slug: "maintainable-codebase",
-    content: `# Maintainable Codebase
+This means accepting some breadth of scope — bundling configs, rules, and utilities that target external tools — in exchange for agents that can start producing useful work immediately without manual setup.
 
-The dust codebase should be easy to understand, modify, and extend.
+## Applicability
 
-This principle governs how we develop and maintain dust itself, separate from the principles that describe what dust offers its users. A well-maintained codebase enables rapid iteration, reduces bugs, and makes contributions easier.
+Internal
 
 ## Parent Principle
 
-- [Agentic Flow State](agentic-flow-state.md)
+- [Agent Autonomy](agent-autonomy.md)
 
 ## Sub-Principles
-
-- [Make Changes with Confidence](make-changes-with-confidence.md)
-- [Minimal Dependencies](minimal-dependencies.md)
-- [Intuitive Directory Structure](intuitive-directory-structure.md)
-- [Repository Hygiene](repository-hygiene.md)
-- [Naming Matters](naming-matters.md)
-- [Reasonably DRY](reasonably-dry.md)
-- [Make the Change Easy](make-the-change-easy.md)
-- [Boy Scout Rule](boy-scout-rule.md)
-- [Broken Windows](broken-windows.md)
 `
   },
   {
-    slug: "agent-agnostic-design",
-    content: `# Agent-Agnostic Design
-
-Dust should work with multiple agents without favoring one.
+    slug: "development-traceability",
+    content: `# Development Traceability
 
-Rather than implementing agents, Dust generates prompts and context that can be passed to any capable agent. This keeps Dust lightweight and allows teams to use whatever agent tooling they prefer.
+Structured logging and tracing help agents understand system behaviour without resorting to ad-hoc testing cycles.
 
-Dust may have built-in support for invoking popular agents (Claude, Aider, Codex, etc.), but the choice of agent should always be made by the user at runtime - never hard-coded into repository configuration.
+When something goes wrong, agents often resort to adding temporary log statements, running the code, reading the output, and repeating — a slow and wasteful debugging loop. Good traceability means the system already records what happened and why, through structured logs, trace IDs, and observable state. This lets agents diagnose issues by reading existing output rather than generating new experiments.
 
-Note: Supporting multiple agents directly contributes to [Easy Adoption](easy-adoption.md), since teams can use their preferred agent tools without being locked into a specific platform.
+Dust should encourage projects to adopt structured logging, promote traceability as a first-class concern, and provide tools that surface relevant trace information when agents need it.
 
 ## Applicability
 
@@ -12937,7 +13467,7 @@ Internal
 
 ## Parent Principle
 
-- [Agent Autonomy](agent-autonomy.md)
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
 
 ## Sub-Principles
 
@@ -12945,42 +13475,22 @@ Internal
 `
   },
   {
-    slug: "easy-adoption",
-    content: `# Easy Adoption
-
-Dust should be trivially easy to adopt in any repository.
-
-Getting started with Dust should require minimal friction. A developer should be able to bootstrap Dust in their repository with a single command, without needing to install dependencies, configure build tools, or understand the internals.
-
-This lowers the barrier to entry and encourages experimentation.
-
-## Parent Principle
-
-- [Human-AI Collaboration](human-ai-collaboration.md)
+    slug: "exploratory-tooling",
+    content: `# Exploratory Tooling
 
-## Sub-Principles
+Agents need tools to efficiently explore and understand unfamiliar codebases.
 
-- [Cross-Platform Compatibility](cross-platform-compatibility.md)
-- [Unsurprising UX](unsurprising-ux.md)
-- [VCS Independence](vcs-independence.md)
-`
-  },
-  {
-    slug: "actionable-errors",
-    content: `# Actionable Errors
+When an agent encounters a new codebase — or an unfamiliar corner of a familiar one — it needs to quickly build a mental model: what exists, how it fits together, and where to make changes. Without good exploratory tools, agents waste context on trial-and-error searches, reading irrelevant files, and forming incorrect assumptions.
 
-Error messages should tell you what to do next, not just what went wrong.
+Dust should promote and integrate tools that help agents explore: dependency graphs, module overviews, search utilities tuned for code navigation, and summaries of project structure. The goal is to make the "orientation" phase of any task as short and reliable as possible.
 
-When something fails, the message should provide:
-- A clear description of the problem
-- Specific guidance on how to fix it
-- Context needed to take the next step
+## Applicability
 
-This is especially important for AI agents, who need concrete instructions to recover autonomously. A good error message turns a dead end into a signpost.
+Internal
 
 ## Parent Principle
 
-- [Agent Autonomy](agent-autonomy.md)
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
 
 ## Sub-Principles
 
@@ -12988,71 +13498,57 @@ This is especially important for AI agents, who need concrete instructions to re
 `
   },
   {
-    slug: "consistent-naming",
-    content: `# Consistent Naming
-
-Names should follow established conventions within each category to reduce cognitive load.
-
-Principles use Title Case. File names use kebab-case. Commands use lowercase with hyphens. When naming conventions exist, follow them. When they don't, establish one and apply it consistently. Inconsistent naming creates friction for both humans and AI agents trying to predict or recall identifiers.
-
-## Parent Principle
-
-- [Naming Matters](naming-matters.md)
+    slug: "small-units",
+    content: `# Small Units
 
-## Sub-Principles
+Ideas, principles, facts, and tasks should each be as discrete and fine-grained as possible.
 
-- (none)
-`
-  },
-  {
-    slug: "minimal-dependencies",
-    content: `# Minimal Dependencies
+Small, focused documents enable precise relationships between them. A task can link to exactly the principles it serves. A fact can describe one specific aspect of the system. This granularity reduces ambiguity.
 
-Dust should avoid coupling to specific tools so we can switch to better alternatives as they emerge.
+Tasks especially benefit from being small. A narrowly scoped task gives agents or humans the best chance of delivering exactly what was intended, in a single atomic commit.
 
-By keeping dependencies minimal and using standard APIs where possible, we maintain the freedom to adopt new tools without major rewrites. This applies to runtimes, test frameworks, build tools, and other infrastructure choices.
+Note: This principle directly supports [Lightweight Planning](lightweight-planning.md), which explicitly mentions that "Tasks are small and completable in single commits."
 
 ## Parent Principle
 
-- [Maintainable Codebase](maintainable-codebase.md)
+- [Agent Autonomy](agent-autonomy.md)
 
 ## Sub-Principles
 
-- [Runtime Agnostic Tests](runtime-agnostic-tests.md)
+- (none)
 `
   },
   {
-    slug: "context-window-efficiency",
-    content: `# Context Window Efficiency
-
-Dust should be designed with short attention spans in mind.
+    slug: "naming-matters",
+    content: `# Naming Matters
 
-AI agents operate within limited context windows. Every token consumed by planning artifacts is a token unavailable for reasoning about code. Dust keeps artifacts concise and scannable so agents can quickly understand what needs to be done without wading through verbose documentation.
+Good naming reduces waste by eliminating confusion and making code self-documenting.
 
-This means favoring brevity over completeness, using consistent structures that are fast to parse, and avoiding redundant information across files.
+Poor names cause rework, bugs, and communication overhead. When names don't clearly convey meaning, developers waste time deciphering code, misunderstand intentions, and introduce defects. Well-chosen names serve as documentation that never goes stale, reducing the need for explanatory comments and enabling both humans and AI agents to navigate the codebase efficiently.
 
 ## Parent Principle
 
-- [Agent Autonomy](agent-autonomy.md)
+- [Maintainable Codebase](maintainable-codebase.md)
 
 ## Sub-Principles
 
-- [Progressive Disclosure](progressive-disclosure.md)
+- [Consistent Naming](consistent-naming.md)
+- [Clarity Over Brevity](clarity-over-brevity.md)
 `
   },
   {
-    slug: "boy-scout-rule",
-    content: `# Boy Scout Rule
+    slug: "comprehensive-test-coverage",
+    content: `# Comprehensive Test Coverage
 
-Always leave the code better than you found it.
+A project's test suite is its primary safety net, and agents depend on it even more than humans do.
 
-When working in any area of the codebase, take the opportunity to make small improvements — clearer names, removed dead code, better structure — even if they're not directly related to the task at hand. These incremental improvements compound over time, preventing gradual decay and keeping the codebase healthy without requiring dedicated cleanup efforts.
+Agents cannot manually verify that their changes work. They rely entirely on automated tests to confirm correctness. Gaps in test coverage become gaps in agent capability — areas where changes are risky and feedback is absent. Comprehensive coverage means every meaningful behaviour is tested, so agents can make changes anywhere in the codebase with confidence.
 
-The Boy Scout Rule is not a license for large-scale refactoring during unrelated work. Improvements should be small, obvious, and low-risk. If a cleanup is too large to include alongside the current task, capture it as a separate task instead.
+Dust should help projects measure and improve their test coverage, flag untested areas, and encourage a culture where new code comes with new tests.
 
 ## Parent Principle
 
-- [Maintainable Codebase](maintainable-codebase.md)
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
 
 ## Sub-Principles
 
@@ -13060,18 +13556,16 @@ The Boy Scout Rule is not a license for large-scale refactoring during unrelated
 `
   },
   {
-    slug: "unsurprising-ux",
-    content: `# Unsurprising UX
-
-The user interface should be as "guessable" as possible.
+    slug: "stop-the-line",
+    content: `# Stop the Line
 
-Following the [Principle of Least Astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment), users form expectations about how a tool will behave based on conventions, prior experience, and intuition. Dust's interface (including the CLI) should match those expectations wherever possible. If users are observed trying to use the interface in ways we didn't anticipate, the interface should be adjusted to meet their expectations — even if that means supporting many ways of achieving the same result.
+Any worker — human or agent — should halt and fix a problem the moment they detect it, rather than letting defects propagate downstream.
 
-Surprising behavior erodes trust and slows people down. Unsurprising behavior lets users stay in flow.
+Originating from the Toyota production system, "Stop the Line" empowers every participant to pause work immediately upon identifying a defect, failing check, or safety hazard. Problems are cheaper to fix at their source than after they've compounded through later stages. In the context of dust, this means agents and humans alike should treat broken checks, test failures, and lint errors as blockers that demand immediate attention — not warnings to be deferred.
 
 ## Parent Principle
 
-- [Easy Adoption](easy-adoption.md)
+- [Make Changes with Confidence](make-changes-with-confidence.md)
 
 ## Sub-Principles
 
@@ -13081,10 +13575,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 +13622,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 +13652,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 +13661,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 +13871,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 +13940,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 +13948,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 +14058,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) {