@joshski/dust 0.1.58 → 0.1.59

package/dist/cli/types.d.ts

@@ -24,6 +24,7 @@ export interface FileSystem {
     chmod: (path: string, mode: number) => Promise<void>;
     isDirectory: (path: string) => boolean;
     getFileCreationTime: (path: string) => number;
+    rename: (oldPath: string, newPath: string) => Promise<void>;
 }
 export interface GlobScanner {
     scan: (dir: string) => AsyncIterable<string>;
@@ -41,6 +42,7 @@ export interface DustSettings {
     eventsUrl?: string;
     extraDirectories?: string[];
 }
+export type DirectoryFileSorter = (dir: string, files: string[]) => Promise<string[]>;
 /**
  * Dependencies passed to all CLI commands
  */
@@ -50,4 +52,5 @@ export interface CommandDependencies {
     fileSystem: FileSystem;
     globScanner: GlobScanner;
     settings: DustSettings;
+    directoryFileSorter?: DirectoryFileSorter;
 }

package/dist/dust.js

@@ -1,7 +1,33 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
 // lib/cli/run.ts
 import { existsSync, statSync as statSync2 } from "node:fs";
-import { chmod as chmod2, mkdir as mkdir2, readdir as readdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import {
+  chmod as chmod2,
+  mkdir as mkdir2,
+  readdir as readdir2,
+  readFile as readFile2,
+  rename,
+  writeFile as writeFile2
+} from "node:fs/promises";
+
+// lib/git/file-sorter.ts
+function createGitDirectoryFileSorter(gitRunner) {
+  return async (dir, files) => {
+    const timestamps = 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
+      };
+    }));
+    timestamps.sort((a, b) => a.timestamp - b.timestamp);
+    return timestamps.map((t) => t.file);
+  };
+}
 
 // lib/config/settings.ts
 import { join } from "node:path";
@@ -481,8 +507,8 @@ ${vars.agentInstructions}` : "";
     3. **Capture a new task** → \`${vars.bin} new task\`
        User has concrete work to add. Keywords: "task: ..." or "add a task ..."
 
-    4. **Capture a new goal** → \`${vars.bin} new goal\`
-       User has a higher-level objective to add. Keywords: "goal: ..." or "add a goal ..."
+    4. **Capture a new principle** → \`${vars.bin} new principle\`
+       User has a guiding value to add. Keywords: "principle: ..." or "add a principle ..."
 
     5. **Capture a vague idea** → \`${vars.bin} new idea\`
        User has a rough idea that might become work later. Keywords: "idea: ..." or "add an idea ..."
@@ -577,7 +603,7 @@ function agentDeveloperExperience() {
     4. **Debugging tools** - Can agents diagnose issues without trial and error?
     5. **Structured logging** - Is system behavior observable through logs?
 
-    ## Goals
+    ## Principles
 
     (none)
 
@@ -610,7 +636,7 @@ function deadCode() {
     4. **Unused dependencies** - Packages in package.json not used in code
     5. **Commented-out code** - Old code left in comments
 
-    ## Goals
+    ## Principles
 
     (none)
 
@@ -644,7 +670,7 @@ function factsVerification() {
     3. **Staleness** - Have facts become outdated due to recent changes?
     4. **Relevance** - Are all facts still useful for understanding the project?
 
-    ## Goals
+    ## Principles
 
     (none)
 
@@ -677,7 +703,7 @@ function ideasFromCommits() {
     3. **Pattern opportunities** - Can recent changes be generalized?
     4. **Test gaps** - Do recent changes have adequate test coverage?
 
-    ## Goals
+    ## Principles
 
     (none)
 
@@ -694,22 +720,22 @@ function ideasFromCommits() {
     - [ ] Proposed follow-up ideas for any issues identified
   `;
 }
-function ideasFromGoals() {
+function ideasFromPrinciples() {
   return dedent`
-    # Ideas from Goals
+    # Ideas from Principles
 
-    Review \`.dust/goals/\` to generate new improvement ideas. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues or opportunities you identify, avoiding duplication.
+    Review \`.dust/principles/\` to generate new improvement ideas. Review existing ideas in \`./.ideas/\` and the recent history of \`./.dust/ideas\` to understand what has been proposed or considered historically, then create new idea files in \`./.ideas/\` for any issues or opportunities you identify, avoiding duplication.
 
     ## Scope
 
     Focus on these areas:
 
-    1. **Unmet goals** - Which goals lack supporting work?
-    2. **Gap analysis** - Where does the codebase fall short of goals?
-    3. **New opportunities** - What work would better achieve each goal?
-    4. **Goal alignment** - Are current tasks aligned with stated goals?
+    1. **Unmet principles** - Which principles lack supporting work?
+    2. **Gap analysis** - Where does the codebase fall short of principles?
+    3. **New opportunities** - What work would better achieve each principle?
+    4. **Principle alignment** - Are current tasks aligned with stated principles?
 
-    ## Goals
+    ## Principles
 
     (none)
 
@@ -719,10 +745,10 @@ function ideasFromGoals() {
 
     ## Definition of Done
 
-    - [ ] Read each goal file in \`.dust/goals/\`
-    - [ ] Analyzed codebase for alignment with each goal
-    - [ ] Listed gaps between current state and goal intent
-    - [ ] Proposed new ideas for unmet or underserved goals
+    - [ ] Read each principle file in \`.dust/principles/\`
+    - [ ] Analyzed codebase for alignment with each principle
+    - [ ] Listed gaps between current state and principle intent
+    - [ ] Proposed new ideas for unmet or underserved principles
   `;
 }
 function performanceReview() {
@@ -741,7 +767,7 @@ function performanceReview() {
     4. **Build performance** - How fast is the build process?
     5. **Test speed** - Are tests running efficiently?
 
-    ## Goals
+    ## Principles
 
     (none)
 
@@ -774,7 +800,7 @@ function securityReview() {
     4. **Sensitive data exposure** - Logging sensitive data, insecure storage
     5. **Dependency vulnerabilities** - Known CVEs in dependencies
 
-    ## Goals
+    ## Principles
 
     (none)
 
@@ -808,7 +834,7 @@ function staleIdeas() {
     3. **Actionability** - Can the idea be converted to a task?
     4. **Duplication** - Are there overlapping or redundant ideas?
 
-    ## Goals
+    ## Principles
 
     (none)
 
@@ -841,7 +867,7 @@ function testCoverage() {
     4. **User-facing features** - UI components, form validation
     5. **Recent changes** - Code modified in the last few commits
 
-    ## Goals
+    ## Principles
 
     (none)
 
@@ -862,7 +888,7 @@ var stockAuditFunctions = {
   "dead-code": deadCode,
   "facts-verification": factsVerification,
   "ideas-from-commits": ideasFromCommits,
-  "ideas-from-goals": ideasFromGoals,
+  "ideas-from-principles": ideasFromPrinciples,
   "performance-review": performanceReview,
   "security-review": securityReview,
   "stale-ideas": staleIdeas,
@@ -1874,7 +1900,7 @@ function extractBlockedBy(content) {
   }
   return blockers;
 }
-async function findUnblockedTasks(cwd, fileSystem) {
+async function findUnblockedTasks(cwd, fileSystem, directoryFileSorter) {
   const dustPath = `${cwd}/.dust`;
   if (!fileSystem.exists(dustPath)) {
     return { error: ".dust directory not found", tasks: [] };
@@ -1884,11 +1910,16 @@ async function findUnblockedTasks(cwd, fileSystem) {
     return { tasks: [] };
   }
   const files = await fileSystem.readdir(tasksPath);
-  const mdFiles = files.filter((f) => f.endsWith(".md")).sort((a, b) => {
-    const aTime = fileSystem.getFileCreationTime(`${tasksPath}/${a}`);
-    const bTime = fileSystem.getFileCreationTime(`${tasksPath}/${b}`);
-    return aTime - bTime;
-  });
+  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;
+    });
+  }
   if (mdFiles.length === 0) {
     return { tasks: [] };
   }
@@ -1924,8 +1955,8 @@ function printTaskList(context, tasks) {
   }
 }
 async function next(dependencies) {
-  const { context, fileSystem } = dependencies;
-  const result = await findUnblockedTasks(context.cwd, fileSystem);
+  const { context, fileSystem, directoryFileSorter } = dependencies;
+  const result = await findUnblockedTasks(context.cwd, fileSystem, directoryFileSorter);
   if (result.error) {
     context.stderr(`Error: ${result.error}`);
     context.stderr("Run 'dust init' to initialize a Dust repository");
@@ -2059,8 +2090,8 @@ async function gitPull(cwd, spawn) {
   });
 }
 async function findAvailableTasks(dependencies) {
-  const { context, fileSystem } = dependencies;
-  const result = await findUnblockedTasks(context.cwd, fileSystem);
+  const { context, fileSystem, directoryFileSorter } = dependencies;
+  const result = await findUnblockedTasks(context.cwd, fileSystem, directoryFileSorter);
   return result.tasks;
 }
 async function runOneIteration(dependencies, loopDependencies, onLoopEvent, onAgentEvent, options = {}) {
@@ -3047,7 +3078,8 @@ function createDefaultBucketDependencies() {
     writeFile: (path, content) => writeFile(path, content, "utf8"),
     mkdir: (path, options) => mkdir(path, options).then(() => {}),
     readdir: (path) => readdir(path),
-    chmod: (path, mode) => chmod(path, mode)
+    chmod: (path, mode) => chmod(path, mode),
+    rename: (oldPath, newPath) => import("node:fs/promises").then((mod) => mod.rename(oldPath, newPath))
   };
   return {
     spawn: nodeSpawn3,
@@ -3488,7 +3520,11 @@ function runBufferedProcess(spawnFn, command, commandArguments, cwd, shell, time
 import { join as join10 } from "node:path";
 
 // lib/lint/validators/content-validator.ts
-var REQUIRED_HEADINGS = ["## Goals", "## Blocked By", "## Definition of Done"];
+var REQUIRED_HEADINGS = [
+  "## Principles",
+  "## Blocked By",
+  "## Definition of Done"
+];
 var MAX_OPENING_SENTENCE_LENGTH = 150;
 var NON_IMPERATIVE_STARTERS = new Set([
   "the",
@@ -3557,7 +3593,7 @@ function validateTaskHeadings(filePath, content) {
 }
 
 // lib/lint/validators/directory-validator.ts
-var EXPECTED_DIRECTORIES = ["goals", "ideas", "tasks", "facts", "config"];
+var EXPECTED_DIRECTORIES = ["principles", "ideas", "tasks", "facts", "config"];
 async function validateContentDirectoryFiles(dirPath, fileSystem) {
   const violations = [];
   let entries;
@@ -3655,117 +3691,6 @@ function validateTitleFilenameMatch(filePath, content) {
   return null;
 }
 
-// lib/lint/validators/goal-hierarchy.ts
-import { dirname as dirname4, resolve } from "node:path";
-var REQUIRED_GOAL_HEADINGS = ["## Parent Goal", "## Sub-Goals"];
-function validateGoalHierarchySections(filePath, content) {
-  const violations = [];
-  for (const heading of REQUIRED_GOAL_HEADINGS) {
-    if (!content.includes(heading)) {
-      violations.push({
-        file: filePath,
-        message: `Missing required heading: "${heading}"`
-      });
-    }
-  }
-  return violations;
-}
-function extractGoalRelationships(filePath, content) {
-  const lines = content.split(`
-`);
-  const fileDir = dirname4(filePath);
-  const parentGoals = [];
-  const subGoals = [];
-  let currentSection = null;
-  for (const line of lines) {
-    if (line.startsWith("## ")) {
-      currentSection = line;
-      continue;
-    }
-    if (currentSection !== "## Parent Goal" && currentSection !== "## Sub-Goals") {
-      continue;
-    }
-    const linkPattern = new RegExp(MARKDOWN_LINK_PATTERN.source, "g");
-    let match = linkPattern.exec(line);
-    while (match) {
-      const linkTarget = match[2];
-      if (!linkTarget.startsWith("#") && !linkTarget.startsWith("http://") && !linkTarget.startsWith("https://")) {
-        const targetPath = linkTarget.split("#")[0];
-        const resolvedPath = resolve(fileDir, targetPath);
-        if (resolvedPath.includes("/.dust/goals/")) {
-          if (currentSection === "## Parent Goal") {
-            parentGoals.push(resolvedPath);
-          } else {
-            subGoals.push(resolvedPath);
-          }
-        }
-      }
-      match = linkPattern.exec(line);
-    }
-  }
-  return { filePath, parentGoals, subGoals };
-}
-function validateBidirectionalLinks(allGoalRelationships) {
-  const violations = [];
-  const relationshipMap = new Map;
-  for (const rel of allGoalRelationships) {
-    relationshipMap.set(rel.filePath, rel);
-  }
-  for (const rel of allGoalRelationships) {
-    for (const parentPath of rel.parentGoals) {
-      const parentRel = relationshipMap.get(parentPath);
-      if (parentRel && !parentRel.subGoals.includes(rel.filePath)) {
-        violations.push({
-          file: rel.filePath,
-          message: `Parent goal "${parentPath}" does not list this goal as a sub-goal`
-        });
-      }
-    }
-    for (const subGoalPath of rel.subGoals) {
-      const subGoalRel = relationshipMap.get(subGoalPath);
-      if (subGoalRel && !subGoalRel.parentGoals.includes(rel.filePath)) {
-        violations.push({
-          file: rel.filePath,
-          message: `Sub-goal "${subGoalPath}" does not list this goal as its parent`
-        });
-      }
-    }
-  }
-  return violations;
-}
-function validateNoCycles(allGoalRelationships) {
-  const violations = [];
-  const relationshipMap = new Map;
-  for (const rel of allGoalRelationships) {
-    relationshipMap.set(rel.filePath, rel);
-  }
-  for (const rel of allGoalRelationships) {
-    const visited = new Set;
-    const path = [];
-    let current = rel.filePath;
-    while (current) {
-      if (visited.has(current)) {
-        const cycleStart = path.indexOf(current);
-        const cyclePath = path.slice(cycleStart).concat(current);
-        violations.push({
-          file: rel.filePath,
-          message: `Cycle detected in goal hierarchy: ${cyclePath.join(" -> ")}`
-        });
-        break;
-      }
-      visited.add(current);
-      path.push(current);
-      const currentRel = relationshipMap.get(current);
-      if (currentRel && currentRel.parentGoals.length > 0) {
-        current = currentRel.parentGoals[0];
-      } else {
-        current = null;
-      }
-    }
-  }
-  return violations;
-}
-
 // lib/lint/validators/idea-validator.ts
 function validateIdeaOpenQuestions(filePath, content) {
   const violations = [];
@@ -3882,12 +3807,12 @@ function validateIdeaTransitionTitle(filePath, content, ideasPath, fileSystem) {
 }
 
 // lib/lint/validators/link-validator.ts
-import { dirname as dirname5, resolve as resolve2 } from "node:path";
+import { dirname as dirname4, resolve } from "node:path";
 var SEMANTIC_RULES = [
   {
-    section: "## Goals",
-    requiredPath: "/.dust/goals/",
-    description: "goal"
+    section: "## Principles",
+    requiredPath: "/.dust/principles/",
+    description: "principle"
   },
   {
     section: "## Blocked By",
@@ -3899,7 +3824,7 @@ function validateLinks(filePath, content, fileSystem) {
   const violations = [];
   const lines = content.split(`
 `);
-  const fileDir = dirname5(filePath);
+  const fileDir = dirname4(filePath);
   for (let i = 0;i < lines.length; i++) {
     const line = lines[i];
     const linkPattern = new RegExp(MARKDOWN_LINK_PATTERN.source, "g");
@@ -3908,7 +3833,7 @@ function validateLinks(filePath, content, fileSystem) {
       const linkTarget = match[2];
       if (!linkTarget.startsWith("http://") && !linkTarget.startsWith("https://") && !linkTarget.startsWith("#")) {
         const targetPath = linkTarget.split("#")[0];
-        const resolvedPath = resolve2(fileDir, targetPath);
+        const resolvedPath = resolve(fileDir, targetPath);
         if (!fileSystem.exists(resolvedPath)) {
           violations.push({
             file: filePath,
@@ -3926,7 +3851,7 @@ function validateSemanticLinks(filePath, content) {
   const violations = [];
   const lines = content.split(`
 `);
-  const fileDir = dirname5(filePath);
+  const fileDir = dirname4(filePath);
   let currentSection = null;
   for (let i = 0;i < lines.length; i++) {
     const line = lines[i];
@@ -3960,7 +3885,7 @@ function validateSemanticLinks(filePath, content) {
         continue;
       }
       const targetPath = linkTarget.split("#")[0];
-      const resolvedPath = resolve2(fileDir, targetPath);
+      const resolvedPath = resolve(fileDir, targetPath);
       if (!resolvedPath.includes(rule.requiredPath)) {
         violations.push({
           file: filePath,
@@ -3973,11 +3898,11 @@ function validateSemanticLinks(filePath, content) {
   }
   return violations;
 }
-function validateGoalHierarchyLinks(filePath, content) {
+function validatePrincipleHierarchyLinks(filePath, content) {
   const violations = [];
   const lines = content.split(`
 `);
-  const fileDir = dirname5(filePath);
+  const fileDir = dirname4(filePath);
   let currentSection = null;
   for (let i = 0;i < lines.length; i++) {
     const line = lines[i];
@@ -3985,7 +3910,7 @@ function validateGoalHierarchyLinks(filePath, content) {
       currentSection = line;
       continue;
     }
-    if (currentSection !== "## Parent Goal" && currentSection !== "## Sub-Goals") {
+    if (currentSection !== "## Parent Principle" && currentSection !== "## Sub-Principles") {
       continue;
     }
     const linkPattern = new RegExp(MARKDOWN_LINK_PATTERN.source, "g");
@@ -3995,7 +3920,7 @@ function validateGoalHierarchyLinks(filePath, content) {
       if (linkTarget.startsWith("#")) {
         violations.push({
           file: filePath,
-          message: `Link in "${currentSection}" must point to a goal file, not an anchor: "${linkTarget}"`,
+          message: `Link in "${currentSection}" must point to a principle file, not an anchor: "${linkTarget}"`,
           line: i + 1
         });
         match = linkPattern.exec(line);
@@ -4004,18 +3929,18 @@ function validateGoalHierarchyLinks(filePath, content) {
       if (linkTarget.startsWith("http://") || linkTarget.startsWith("https://")) {
         violations.push({
           file: filePath,
-          message: `Link in "${currentSection}" must point to a goal file, not an external URL: "${linkTarget}"`,
+          message: `Link in "${currentSection}" must point to a principle file, not an external URL: "${linkTarget}"`,
           line: i + 1
         });
         match = linkPattern.exec(line);
         continue;
       }
       const targetPath = linkTarget.split("#")[0];
-      const resolvedPath = resolve2(fileDir, targetPath);
-      if (!resolvedPath.includes("/.dust/goals/")) {
+      const resolvedPath = resolve(fileDir, targetPath);
+      if (!resolvedPath.includes("/.dust/principles/")) {
         violations.push({
           file: filePath,
-          message: `Link in "${currentSection}" must point to a goal file: "${linkTarget}"`,
+          message: `Link in "${currentSection}" must point to a principle file: "${linkTarget}"`,
           line: i + 1
         });
       }
@@ -4025,6 +3950,117 @@ function validateGoalHierarchyLinks(filePath, content) {
   return violations;
 }
 
+// lib/lint/validators/principle-hierarchy.ts
+import { dirname as dirname5, resolve as resolve2 } from "node:path";
+var REQUIRED_PRINCIPLE_HEADINGS = ["## Parent Principle", "## Sub-Principles"];
+function validatePrincipleHierarchySections(filePath, content) {
+  const violations = [];
+  for (const heading of REQUIRED_PRINCIPLE_HEADINGS) {
+    if (!content.includes(heading)) {
+      violations.push({
+        file: filePath,
+        message: `Missing required heading: "${heading}"`
+      });
+    }
+  }
+  return violations;
+}
+function extractPrincipleRelationships(filePath, content) {
+  const lines = content.split(`
+`);
+  const fileDir = dirname5(filePath);
+  const parentPrinciples = [];
+  const subPrinciples = [];
+  let currentSection = null;
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      currentSection = line;
+      continue;
+    }
+    if (currentSection !== "## Parent Principle" && currentSection !== "## Sub-Principles") {
+      continue;
+    }
+    const linkPattern = new RegExp(MARKDOWN_LINK_PATTERN.source, "g");
+    let match = linkPattern.exec(line);
+    while (match) {
+      const linkTarget = match[2];
+      if (!linkTarget.startsWith("#") && !linkTarget.startsWith("http://") && !linkTarget.startsWith("https://")) {
+        const targetPath = linkTarget.split("#")[0];
+        const resolvedPath = resolve2(fileDir, targetPath);
+        if (resolvedPath.includes("/.dust/principles/")) {
+          if (currentSection === "## Parent Principle") {
+            parentPrinciples.push(resolvedPath);
+          } else {
+            subPrinciples.push(resolvedPath);
+          }
+        }
+      }
+      match = linkPattern.exec(line);
+    }
+  }
+  return { filePath, parentPrinciples, subPrinciples };
+}
+function validateBidirectionalLinks(allPrincipleRelationships) {
+  const violations = [];
+  const relationshipMap = new Map;
+  for (const rel of allPrincipleRelationships) {
+    relationshipMap.set(rel.filePath, rel);
+  }
+  for (const rel of allPrincipleRelationships) {
+    for (const parentPath of rel.parentPrinciples) {
+      const parentRel = relationshipMap.get(parentPath);
+      if (parentRel && !parentRel.subPrinciples.includes(rel.filePath)) {
+        violations.push({
+          file: rel.filePath,
+          message: `Parent principle "${parentPath}" does not list this principle as a sub-principle`
+        });
+      }
+    }
+    for (const subPrinciplePath of rel.subPrinciples) {
+      const subPrincipleRel = relationshipMap.get(subPrinciplePath);
+      if (subPrincipleRel && !subPrincipleRel.parentPrinciples.includes(rel.filePath)) {
+        violations.push({
+          file: rel.filePath,
+          message: `Sub-principle "${subPrinciplePath}" does not list this principle as its parent`
+        });
+      }
+    }
+  }
+  return violations;
+}
+function validateNoCycles(allPrincipleRelationships) {
+  const violations = [];
+  const relationshipMap = new Map;
+  for (const rel of allPrincipleRelationships) {
+    relationshipMap.set(rel.filePath, rel);
+  }
+  for (const rel of allPrincipleRelationships) {
+    const visited = new Set;
+    const path = [];
+    let current = rel.filePath;
+    while (current) {
+      if (visited.has(current)) {
+        const cycleStart = path.indexOf(current);
+        const cyclePath = path.slice(cycleStart).concat(current);
+        violations.push({
+          file: rel.filePath,
+          message: `Cycle detected in principle hierarchy: ${cyclePath.join(" -> ")}`
+        });
+        break;
+      }
+      visited.add(current);
+      path.push(current);
+      const currentRel = relationshipMap.get(current);
+      if (currentRel && currentRel.parentPrinciples.length > 0) {
+        current = currentRel.parentPrinciples[0];
+      } else {
+        current = null;
+      }
+    }
+  }
+  return violations;
+}
+
 // lib/cli/commands/lint-markdown.ts
 async function safeScanDir(glob, dirPath) {
   const files = [];
@@ -4085,7 +4121,7 @@ async function lintMarkdown(dependencies) {
       }
     }
   }
-  const contentDirs = ["goals", "facts", "ideas", "tasks"];
+  const contentDirs = ["principles", "facts", "ideas", "tasks"];
   context.stdout("Validating content files...");
   for (const dir of contentDirs) {
     const dirPath = `${dustPath}/${dir}`;
@@ -4174,15 +4210,15 @@ async function lintMarkdown(dependencies) {
       }
     }
   }
-  const goalsPath = `${dustPath}/goals`;
-  const { files: goalFiles } = await safeScanDir(glob, goalsPath);
-  if (goalFiles.length > 0) {
-    context.stdout("Validating goal hierarchy in .dust/goals/...");
-    const allGoalRelationships = [];
-    for (const file of goalFiles) {
+  const principlesPath = `${dustPath}/principles`;
+  const { files: principleFiles } = await safeScanDir(glob, principlesPath);
+  if (principleFiles.length > 0) {
+    context.stdout("Validating principle hierarchy in .dust/principles/...");
+    const allPrincipleRelationships = [];
+    for (const file of principleFiles) {
       if (!file.endsWith(".md"))
         continue;
-      const filePath = `${goalsPath}/${file}`;
+      const filePath = `${principlesPath}/${file}`;
       let content;
       try {
         content = await fileSystem.readFile(filePath);
@@ -4192,12 +4228,12 @@ async function lintMarkdown(dependencies) {
         }
         throw error;
       }
-      violations.push(...validateGoalHierarchySections(filePath, content));
-      violations.push(...validateGoalHierarchyLinks(filePath, content));
-      allGoalRelationships.push(extractGoalRelationships(filePath, content));
+      violations.push(...validatePrincipleHierarchySections(filePath, content));
+      violations.push(...validatePrincipleHierarchyLinks(filePath, content));
+      allPrincipleRelationships.push(extractPrincipleRelationships(filePath, content));
     }
-    violations.push(...validateBidirectionalLinks(allGoalRelationships));
-    violations.push(...validateNoCycles(allGoalRelationships));
+    violations.push(...validateBidirectionalLinks(allPrincipleRelationships));
+    violations.push(...validateNoCycles(allPrincipleRelationships));
   }
   if (violations.length === 0) {
     context.stdout("All validations passed!");
@@ -4390,10 +4426,10 @@ function generateHelpText(settings) {
     Commands:
       init              Initialize a new Dust repository
       lint              Run lint checks on .dust/ files
-      list              List all items (tasks, ideas, goals, facts)
+      list              List all items (tasks, ideas, principles, facts)
       tasks             List tasks (actionable work with definitions of done)
       ideas             List ideas (vague proposals, convert to tasks when ready)
-      goals             List goals (guiding principles, stable, rarely change)
+      principles        List principles (guiding values, stable, rarely change)
       facts             List facts (documentation of current system state)
       next              Show tasks ready to work on (not blocked)
       check             Run project-defined quality gate hook
@@ -4402,7 +4438,7 @@ function generateHelpText(settings) {
       pick task         Pick the next task to work on
       implement task    Implement a task
       new task          Create a new task
-      new goal          Create a new goal
+      new principle     Create a new principle
       new idea          Create a new idea
       loop claude       Run continuous Claude iteration on tasks
       pre push          Git pre-push hook validation
@@ -4411,10 +4447,10 @@ function generateHelpText(settings) {
     🤖 Agent Guide
 
     Dust is a lightweight planning system. The .dust/ directory contains:
-    - goals/  - Guiding principles (stable, rarely change)
-    - ideas/  - Proposals (convert to tasks when ready)
-    - tasks/  - Actionable work with definitions of done
-    - facts/  - Documentation of current system state
+    - principles/  - Guiding values (stable, rarely change)
+    - ideas/       - Proposals (convert to tasks when ready)
+    - tasks/       - Actionable work with definitions of done
+    - facts/       - Documentation of current system state
 
     Workflow: Pick a task → implement it → delete the task file → commit atomically.
 
@@ -4436,7 +4472,7 @@ async function implementTask(dependencies) {
 }
 
 // lib/cli/commands/init.ts
-var DUST_DIRECTORIES = ["goals", "ideas", "tasks", "facts", "config"];
+var DUST_DIRECTORIES = ["principles", "ideas", "tasks", "facts", "config"];
 function generateSettings(cwd, fileSystem) {
   const dustCommand = detectDustCommand(cwd, fileSystem);
   const testCommand = detectTestCommand(cwd, fileSystem);
@@ -4538,35 +4574,35 @@ async function init(dependencies) {
   context.stdout(`   ${colors.cyan}>${colors.reset} ${runner} claude "Idea: friendly UI for non-technical users"`);
   context.stdout(`   ${colors.cyan}>${colors.reset} ${runner} codex "Task: set up code coverage"`);
   context.stdout("");
-  context.stdout(`${colors.dim}If this is an existing codebase, you might want to backfill goals and facts:${colors.reset}`);
-  context.stdout(`   ${colors.cyan}>${colors.reset} ${runner} claude "Add goals and facts based on the code in this repository"`);
+  context.stdout(`${colors.dim}If this is an existing codebase, you might want to backfill principles and facts:${colors.reset}`);
+  context.stdout(`   ${colors.cyan}>${colors.reset} ${runner} claude "Add principles and facts based on the code in this repository"`);
   return { exitCode: 0 };
 }
 
 // lib/cli/commands/list.ts
 import { basename as basename2 } from "node:path";
-var VALID_TYPES = ["tasks", "ideas", "goals", "facts"];
+var VALID_TYPES = ["tasks", "ideas", "principles", "facts"];
 var SECTION_HEADERS = {
   tasks: "\uD83D\uDCCB Tasks",
   ideas: "\uD83D\uDCA1 Ideas",
-  goals: "\uD83C\uDFAF Goals",
+  principles: "\uD83C\uDFAF Principles",
   facts: "\uD83D\uDCC4 Facts"
 };
 var TYPE_EXPLANATIONS = {
   tasks: "Tasks are detailed work plans with dependencies and completion criteria. Each task describes a specific piece of work to be done.",
   ideas: "Ideas are future feature notes and proposals. Ideas capture possibilities that haven't yet been refined into actionable tasks.",
-  goals: "Goals are mission statements and guiding principles. Goals describe desired outcomes and values that inform decision-making.",
+  principles: "Principles are guiding values and design constraints. Principles describe how decisions should be made and what matters most.",
   facts: "Facts are current state documentation. Facts capture how things work today, providing context for agents and contributors."
 };
-async function buildGoalHierarchy(goalsPath, fileSystem) {
-  const files = await fileSystem.readdir(goalsPath);
+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 = `${goalsPath}/${file}`;
+    const filePath = `${principlesPath}/${file}`;
     const content = await fileSystem.readFile(filePath);
-    relationships.push(extractGoalRelationships(filePath, content));
+    relationships.push(extractPrincipleRelationships(filePath, content));
     const title = extractTitle(content) || basename2(file, ".md");
     titleMap.set(filePath, title);
   }
@@ -4574,12 +4610,12 @@ async function buildGoalHierarchy(goalsPath, fileSystem) {
   for (const rel of relationships) {
     relMap.set(rel.filePath, rel);
   }
-  const rootGoals = relationships.filter((rel) => rel.parentGoals.length === 0);
+  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.subGoals) {
+      for (const childPath of rel.subPrinciples) {
         children.push(buildNode(childPath));
       }
     }
@@ -4589,7 +4625,7 @@ async function buildGoalHierarchy(goalsPath, fileSystem) {
       children
     };
   }
-  return rootGoals.map((rel) => buildNode(rel.filePath));
+  return rootPrinciples.map((rel) => buildNode(rel.filePath));
 }
 function renderHierarchy(nodes, output, prefix = "") {
   for (let i = 0;i < nodes.length; i++) {
@@ -4639,8 +4675,8 @@ async function list(dependencies) {
     context.stdout("");
     context.stdout(TYPE_EXPLANATIONS[type]);
     context.stdout("");
-    if (type === "goals") {
-      const hierarchy = await buildGoalHierarchy(dirPath, fileSystem);
+    if (type === "principles") {
+      const hierarchy = await buildPrincipleHierarchy(dirPath, fileSystem);
       if (hierarchy.length > 0) {
         context.stdout(`${colors.dim}Hierarchy:${colors.reset}`);
         renderHierarchy(hierarchy, (line) => context.stdout(line));
@@ -4803,37 +4839,68 @@ async function loopCodex(dependencies, loopDependencies = createCodexDependencie
   });
 }
 
-// lib/cli/commands/new-goal.ts
-function newGoalInstructions(vars) {
-  const intro = vars.isClaudeCodeWeb ? "Follow these steps. Use a todo list to track your progress." : "Follow these steps:";
-  return dedent`
-    ## Adding a New Goal
-
-    Goals are guiding principles that persist across tasks. They define the "why" behind the work.
-
-    ${intro}
-    1. Run \`${vars.bin} goals\` to see existing goals and avoid duplication
-    2. Create a new markdown file in \`.dust/goals/\` with a descriptive kebab-case name (e.g., \`cross-platform-support.md\`)
-    3. Add a title as the first line using an H1 heading (e.g., \`# Cross-platform support\`)
-    4. Write a clear description explaining:
-       - What this goal means in practice
-       - Why it matters for the project
-       - How to evaluate whether work supports this goal
-    5. Run \`${vars.bin} lint\` to catch any formatting issues
-    6. Create a single atomic commit with a message in the format "Add goal: <title>"
-    7. Push your commit to the remote repository
-
-    Goals should be:
-    - **Stable** - They rarely change once established
-    - **Actionable** - Tasks can be linked to them
-    - **Clear** - Anyone reading should understand what it means
-  `;
+// lib/cli/commands/migrate.ts
+async function scanMarkdownFiles(glob, dirPath) {
+  const files = [];
+  try {
+    for await (const file of glob.scan(dirPath)) {
+      if (file.endsWith(".md")) {
+        files.push(`${dirPath}/${file}`);
+      }
+    }
+    return files;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
 }
-async function newGoal(dependencies) {
-  const { context, settings } = dependencies;
-  const hooksInstalled = await manageGitHooks(dependencies);
-  const vars = templateVariables(settings, hooksInstalled);
-  context.stdout(newGoalInstructions(vars));
+async function migrate(dependencies) {
+  const { context, fileSystem, globScanner } = dependencies;
+  const colors = getColors();
+  const dustPath = `${context.cwd}/.dust`;
+  const goalsPath = `${dustPath}/goals`;
+  const principlesPath = `${dustPath}/principles`;
+  const dustExists = fileSystem.exists(dustPath);
+  if (!dustExists) {
+    context.stderr(`${colors.yellow}Error:${colors.reset} .dust directory not found. Run '${colors.cyan}dust init${colors.reset}' first.`);
+    return { exitCode: 1 };
+  }
+  const goalsExists = fileSystem.exists(goalsPath);
+  const principlesExists = fileSystem.exists(principlesPath);
+  if (!goalsExists && principlesExists) {
+    context.stdout(`${colors.green}✓${colors.reset} Already migrated - .dust/principles/ exists`);
+    return { exitCode: 0 };
+  }
+  if (!goalsExists && !principlesExists) {
+    context.stdout(`${colors.yellow}⚠️${colors.reset} No .dust/goals/ directory found. Creating .dust/principles/...`);
+    await fileSystem.mkdir(principlesPath, { recursive: true });
+    return { exitCode: 0 };
+  }
+  let updatedFilesCount = 0;
+  context.stdout(`${colors.cyan}→${colors.reset} Renaming .dust/goals/ to .dust/principles/...`);
+  await fileSystem.rename(goalsPath, principlesPath);
+  context.stdout(`${colors.cyan}→${colors.reset} Updating references in markdown files...`);
+  const markdownFiles = await scanMarkdownFiles(globScanner, dustPath);
+  for (const filePath of markdownFiles) {
+    const content = await fileSystem.readFile(filePath);
+    let updated = content;
+    updated = updated.replace(/## Goals\b/g, "## Principles");
+    updated = updated.replace(/## Parent Goal\b/g, "## Parent Principle");
+    updated = updated.replace(/## Sub-Goals\b/g, "## Sub-Principles");
+    updated = updated.replace(/\.\.\/goals\//g, "../principles/");
+    if (updated !== content) {
+      await fileSystem.writeFile(filePath, updated);
+      updatedFilesCount++;
+    }
+  }
+  context.stdout("");
+  context.stdout(`${colors.green}✓${colors.reset} Migration complete!`);
+  context.stdout(`  ${colors.dim}• Renamed .dust/goals/ → .dust/principles/${colors.reset}`);
+  if (updatedFilesCount > 0) {
+    context.stdout(`  ${colors.dim}• Updated ${updatedFilesCount} markdown file(s)${colors.reset}`);
+  }
   return { exitCode: 0 };
 }
 
@@ -4896,6 +4963,40 @@ async function newIdea(dependencies) {
   return { exitCode: 0 };
 }
 
+// lib/cli/commands/new-principle.ts
+function newPrincipleInstructions(vars) {
+  const intro = vars.isClaudeCodeWeb ? "Follow these steps. Use a todo list to track your progress." : "Follow these steps:";
+  return dedent`
+    ## Adding a New Principle
+
+    Principles are guiding values that persist across tasks. They define the "why" behind the work.
+
+    ${intro}
+    1. Run \`${vars.bin} principles\` to see existing principles and avoid duplication
+    2. Create a new markdown file in \`.dust/principles/\` with a descriptive kebab-case name (e.g., \`cross-platform-support.md\`)
+    3. Add a title as the first line using an H1 heading (e.g., \`# Cross-platform support\`)
+    4. Write a clear description explaining:
+       - What this principle means in practice
+       - Why it matters for the project
+       - How to evaluate whether work supports this principle
+    5. Run \`${vars.bin} lint\` to catch any formatting issues
+    6. Create a single atomic commit with a message in the format "Add principle: <title>"
+    7. Push your commit to the remote repository
+
+    Principles should be:
+    - **Stable** - They rarely change once established
+    - **Actionable** - Tasks can be linked to them
+    - **Clear** - Anyone reading should understand what it means
+  `;
+}
+async function newPrinciple(dependencies) {
+  const { context, settings } = dependencies;
+  const hooksInstalled = await manageGitHooks(dependencies);
+  const vars = templateVariables(settings, hooksInstalled);
+  context.stdout(newPrincipleInstructions(vars));
+  return { exitCode: 0 };
+}
+
 // lib/cli/commands/new-task.ts
 function newTaskInstructions(vars) {
   const steps = [];
@@ -4922,7 +5023,7 @@ function newTaskInstructions(vars) {
   steps.push("4. Create a new markdown file in `.dust/tasks/` with a descriptive kebab-case name (e.g., `add-user-authentication.md`)");
   steps.push("5. Add a title as the first line using an H1 heading (e.g., `# Add user authentication`)");
   steps.push('6. Write a comprehensive description starting with an imperative opening sentence (e.g., "Add caching to the API layer." not "This task adds caching."). Include technical details and references to relevant files.');
-  steps.push("7. Add a `## Goals` section with links to relevant goals this task supports (e.g., `- [Goal Name](../goals/goal-name.md)`)");
+  steps.push("7. Add a `## Principles` section with links to relevant principles this task supports (e.g., `- [Principle Name](../principles/principle-name.md)`)");
   steps.push("8. Add a `## Blocked By` section listing any tasks that must complete first, or `(none)` if there are no blockers");
   steps.push("9. Add a `## Definition of Done` section with a checklist of completion criteria using `- [ ]` for each item");
   steps.push(`10. Run \`${vars.bin} lint\` to catch any issues with the task format`);
@@ -4949,7 +5050,7 @@ async function newTask(dependencies) {
 async function pickTask(dependencies) {
   const { context, fileSystem, settings } = dependencies;
   await manageGitHooks(dependencies);
-  const result = await findUnblockedTasks(context.cwd, fileSystem);
+  const result = await findUnblockedTasks(context.cwd, fileSystem, dependencies.directoryFileSorter);
   if (result.error) {
     context.stderr(`Error: ${result.error}`);
     context.stderr("Run 'dust init' to initialize a Dust repository");
@@ -5102,8 +5203,8 @@ async function prePush(dependencies, gitRunner = defaultGitRunner, env = process
 async function tasks(dependencies) {
   return list({ ...dependencies, arguments: ["tasks"] });
 }
-async function goals(dependencies) {
-  return list({ ...dependencies, arguments: ["goals"] });
+async function principles(dependencies) {
+  return list({ ...dependencies, arguments: ["principles"] });
 }
 async function ideas(dependencies) {
   return list({ ...dependencies, arguments: ["ideas"] });
@@ -5118,7 +5219,7 @@ var commandRegistry = {
   lint: lintMarkdown,
   list,
   tasks,
-  goals,
+  principles,
   ideas,
   facts,
   next,
@@ -5128,13 +5229,14 @@ var commandRegistry = {
   bucket,
   focus,
   "new task": newTask,
-  "new goal": newGoal,
+  "new principle": newPrinciple,
   "new idea": newIdea,
   "implement task": implementTask,
   "pick task": pickTask,
   "loop claude": loopClaude,
   "loop codex": loopCodex,
   "pre push": prePush,
+  migrate,
   help
 };
 var COMMANDS = Object.keys(commandRegistry).filter((cmd) => !cmd.includes(" "));
@@ -5157,7 +5259,7 @@ function resolveCommand(commandArguments) {
   return { command: null, remaining: commandArguments };
 }
 async function main(options) {
-  const { commandArguments, context, fileSystem, glob } = options;
+  const { commandArguments, context, fileSystem, glob, directoryFileSorter } = options;
   const settings = await loadSettings(context.cwd, fileSystem);
   const helpText = generateHelpText(settings);
   if (isHelpRequest(commandArguments[0])) {
@@ -5175,7 +5277,8 @@ async function main(options) {
     context,
     fileSystem,
     globScanner: glob,
-    settings
+    settings,
+    directoryFileSorter
   };
   return runCommand(command, dependencies);
 }
@@ -5201,7 +5304,8 @@ function createFileSystem(primitives) {
     },
     getFileCreationTime: (path) => primitives.statSync(path).birthtimeMs,
     readdir: (path) => primitives.readdir(path),
-    chmod: (path, mode) => primitives.chmod(path, mode)
+    chmod: (path, mode) => primitives.chmod(path, mode),
+    rename: (oldPath, newPath) => primitives.rename(oldPath, newPath)
   };
 }
 function createGlobScanner(readdir2) {
@@ -5217,6 +5321,7 @@ function createGlobScanner(readdir2) {
 async function wireEntry(fsPrimitives, processPrimitives, consolePrimitives) {
   const fileSystem = createFileSystem(fsPrimitives);
   const glob = createGlobScanner(fsPrimitives.readdir);
+  const directoryFileSorter = createGitDirectoryFileSorter(defaultGitRunner);
   const result = await main({
     commandArguments: processPrimitives.argv.slice(2),
     context: {
@@ -5226,13 +5331,14 @@ async function wireEntry(fsPrimitives, processPrimitives, consolePrimitives) {
       stderr: consolePrimitives.error
     },
     fileSystem,
-    glob
+    glob,
+    directoryFileSorter
   });
   processPrimitives.exit(result.exitCode);
 }
 
 // lib/cli/run.ts
-await wireEntry({ existsSync, statSync: statSync2, readFile: readFile2, writeFile: writeFile2, mkdir: mkdir2, readdir: readdir2, chmod: chmod2 }, {
+await wireEntry({ existsSync, statSync: statSync2, readFile: readFile2, writeFile: writeFile2, mkdir: mkdir2, readdir: readdir2, chmod: chmod2, rename }, {
   argv: process.argv,
   cwd: () => process.cwd(),
   exit: (code) => {

package/dist/workflow-tasks.js

@@ -86,7 +86,7 @@ ${renderResolvedQuestions(options.resolvedQuestions)}
 
 ${openingSentence}
 ${descriptionParagraph}${resolvedSection}
-## Goals
+## Principles
 
 (none)
 
@@ -111,7 +111,7 @@ async function createIdeaTask(fileSystem, dustPath, prefix, ideaSlug, openingSen
   return { filePath };
 }
 async function createRefineIdeaTask(fileSystem, dustPath, ideaSlug, description) {
-  return createIdeaTask(fileSystem, dustPath, "Refine Idea: ", ideaSlug, (ideaTitle) => `Thoroughly research this idea and refine it into a well-defined proposal. Read the idea file, explore the codebase for relevant context, and identify any ambiguity. Where aspects are unclear or could go multiple ways, add open questions to the idea file. Review \`.dust/goals/\` for alignment and \`.dust/facts/\` for relevant design decisions. See [${ideaTitle}](../ideas/${ideaSlug}.md). If you add open questions, use \`## Open Questions\` with \`### Question?\` headings and one or more \`#### Option\` headings beneath each question, and only add questions that are meaningful decisions worth asking.`, [
+  return createIdeaTask(fileSystem, dustPath, "Refine Idea: ", ideaSlug, (ideaTitle) => `Thoroughly research this idea and refine it into a well-defined proposal. Read the idea file, explore the codebase for relevant context, and identify any ambiguity. Where aspects are unclear or could go multiple ways, add open questions to the idea file. Review \`.dust/principles/\` for alignment and \`.dust/facts/\` for relevant design decisions. See [${ideaTitle}](../ideas/${ideaSlug}.md). If you add open questions, use \`## Open Questions\` with \`### Question?\` headings and one or more \`#### Option\` headings beneath each question, and only add questions that are meaningful decisions worth asking.`, [
     "Idea is thoroughly researched with relevant codebase context",
     "Open questions are added for any ambiguous or underspecified aspects",
     "Open questions follow the required heading format and focus on high-value decisions",
@@ -119,9 +119,9 @@ async function createRefineIdeaTask(fileSystem, dustPath, ideaSlug, description)
   ], { description });
 }
 async function decomposeIdea(fileSystem, dustPath, options) {
-  return createIdeaTask(fileSystem, dustPath, "Decompose Idea: ", options.ideaSlug, (ideaTitle) => `Create one or more well-defined tasks from this idea. Prefer smaller, narrowly scoped tasks that each deliver a thin but complete vertical slice of working software -- a path through the system that can be tested end-to-end -- rather than component-oriented tasks (like "add schema" or "build endpoint") that only work once all tasks are done. Split the idea into multiple tasks if it covers more than one logical change. Review \`.dust/goals/\` to link relevant goals and \`.dust/facts/\` for design decisions that should inform the task. See [${ideaTitle}](../ideas/${options.ideaSlug}.md).`, [
+  return createIdeaTask(fileSystem, dustPath, "Decompose Idea: ", options.ideaSlug, (ideaTitle) => `Create one or more well-defined tasks from this idea. Prefer smaller, narrowly scoped tasks that each deliver a thin but complete vertical slice of working software -- a path through the system that can be tested end-to-end -- rather than component-oriented tasks (like "add schema" or "build endpoint") that only work once all tasks are done. Split the idea into multiple tasks if it covers more than one logical change. Review \`.dust/principles/\` to link relevant principles and \`.dust/facts/\` for design decisions that should inform the task. See [${ideaTitle}](../ideas/${options.ideaSlug}.md).`, [
     "One or more new tasks are created in .dust/tasks/",
-    "Task's Goals section links to relevant goals from .dust/goals/",
+    "Task's Principles section links to relevant principles from .dust/principles/",
     "The original idea is deleted or updated to reflect remaining scope"
   ], {
     description: options.description,
@@ -145,13 +145,13 @@ async function createCaptureIdeaTask(fileSystem, dustPath, options) {
     const filePath2 = `${dustPath}/tasks/${filename2}`;
     const content2 = `# ${taskTitle2}
 
-Research this idea thoroughly, then create one or more narrowly-scoped task files in \`.dust/tasks/\`. Review \`.dust/goals/\` and \`.dust/facts/\` for relevant context. Each task should deliver a thin but complete vertical slice of working software.
+Research this idea thoroughly, then create one or more narrowly-scoped task files in \`.dust/tasks/\`. Review \`.dust/principles/\` and \`.dust/facts/\` for relevant context. Each task should deliver a thin but complete vertical slice of working software.
 
 ## Idea Description
 
 ${description}
 
-## Goals
+## Principles
 
 (none)
 
@@ -162,7 +162,7 @@ ${description}
 ## Definition of Done
 
 - [ ] One or more new tasks are created in \`.dust/tasks/\`
-- [ ] Tasks link to relevant goals from \`.dust/goals/\`
+- [ ] Tasks link to relevant principles from \`.dust/principles/\`
 - [ ] Tasks are narrowly scoped vertical slices
 `;
     await fileSystem.writeFile(filePath2, content2);
@@ -175,13 +175,13 @@ ${description}
   const ideaPath = `.dust/ideas/${ideaFilename}`;
   const content = `# ${taskTitle}
 
-Research this idea thoroughly, then create an idea file at \`${ideaPath}\`. Read the codebase for relevant context, flesh out the description, and identify any ambiguity. Where aspects are unclear or could go multiple ways, add open questions to the idea file. If you add open questions, use \`## Open Questions\` with \`### Question?\` headings and one or more \`#### Option\` headings beneath each question, and only add questions that are meaningful decisions worth asking. Review \`.dust/goals/\` and \`.dust/facts/\` for relevant context.
+Research this idea thoroughly, then create an idea file at \`${ideaPath}\`. Read the codebase for relevant context, flesh out the description, and identify any ambiguity. Where aspects are unclear or could go multiple ways, add open questions to the idea file. If you add open questions, use \`## Open Questions\` with \`### Question?\` headings and one or more \`#### Option\` headings beneath each question, and only add questions that are meaningful decisions worth asking. Review \`.dust/principles/\` and \`.dust/facts/\` for relevant context.
 
 ## Idea Description
 
 ${description}
 
-## Goals
+## Principles
 
 (none)
 

package/package.json

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