@joshski/dust 0.1.108 → 0.1.110

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.108",
+    version: "0.1.110",
     description: "Flow state for AI coding agents",
     type: "module",
     bin: {
@@ -409,6 +409,16 @@ function createGitDirectoryFileSorter(gitRunner) {
 
 // lib/config/settings.ts
 import { join as join2 } from "node:path";
+
+// lib/filesystem/error-codes.ts
+function isErrnoException(error) {
+  return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string";
+}
+function isErrorCode(error, code) {
+  return isErrnoException(error) && error.code === code;
+}
+
+// lib/config/settings.ts
 var KNOWN_SETTINGS_KEYS = new Set([
   "dustCommand",
   "checks",
@@ -693,7 +703,7 @@ async function loadSettings(cwd, fileSystem, runtime) {
     }
     return result;
   } catch (error) {
-    if (error.code === "ENOENT") {
+    if (isErrorCode(error, "ENOENT")) {
       const result = {
         dustCommand: detectDustCommand(cwd, fileSystem, runtime)
       };
@@ -711,7 +721,7 @@ async function loadSettings(cwd, fileSystem, runtime) {
 }
 
 // lib/version.ts
-var DUST_VERSION = "0.1.108";
+var DUST_VERSION = "0.1.110";
 
 // lib/cli/middleware.ts
 function applyMiddleware(middlewares, execute) {
@@ -834,7 +844,7 @@ function createHooksManager(cwd, fileSystem, settings) {
         const content = await fileSystem.readFile(prePushPath);
         return content.includes(DUST_HOOK_START);
       } catch (error) {
-        if (error.code === "ENOENT") {
+        if (isErrorCode(error, "ENOENT")) {
           return false;
         }
         throw error;
@@ -862,7 +872,7 @@ ${hookContent}
 `;
         }
       } catch (error) {
-        if (error.code === "ENOENT") {
+        if (isErrorCode(error, "ENOENT")) {
           finalContent = `#!/bin/sh
 
 ${hookContent}
@@ -884,7 +894,7 @@ ${hookContent}
         const match = dustSection.match(/^(.+) pre push$/m);
         return match ? match[1] : null;
       } catch (error) {
-        if (error.code === "ENOENT") {
+        if (isErrorCode(error, "ENOENT")) {
           return null;
         }
         throw error;
@@ -895,7 +905,7 @@ ${hookContent}
       try {
         content = await fileSystem.readFile(prePushPath);
       } catch (error) {
-        if (error.code === "ENOENT") {
+        if (isErrorCode(error, "ENOENT")) {
           return;
         }
         throw error;
@@ -929,7 +939,7 @@ async function loadAgentInstructions(cwd, fileSystem, agentType) {
     const content = await fileSystem.readFile(instructionsPath);
     return content.trim();
   } catch (error) {
-    if (error.code === "ENOENT") {
+    if (isErrorCode(error, "ENOENT")) {
       return "";
     }
     throw error;
@@ -1530,6 +1540,72 @@ function deadCode() {
     - No changes to files outside \`.dust/\`
   `;
 }
+function directoryHierarchy() {
+  return dedent`
+    # Directory Hierarchy
+
+    Review directory structure and create improvement ideas.
+
+    ${ideasHint}
+
+    ## Scope
+
+    Analyze the project's directory organization for these issues:
+
+    1. **Concern mixing** - Directories containing files that serve different purposes
+    2. **Missing grouping** - Related files scattered across multiple locations
+    3. **Depth inconsistency** - Similar directories at inconsistent depths
+    4. **Naming inconsistency** - Directory names that don't follow established patterns
+    5. **Singleton directories** - Directories with only a single file or subdirectory
+    6. **Orphaned files** - Files at inappropriate directory levels
+
+    ## Analysis Steps
+
+    1. **Explore the directory tree** - Walk the project's file system recursively, excluding \`node_modules\`, \`.git\`, \`dist\`, \`build\`, \`coverage\`, and other common build artifact directories
+    2. **Identify issues** - For each of the issue types listed above, look for concrete examples in the directory structure
+    3. **Create ideas** - For each issue found, create an idea file in \`.dust/ideas/\` with:
+       - Descriptive filename based on the issue type and affected paths
+       - The specific paths affected
+       - Why the current structure is problematic
+       - A proposed reorganization
+       - Migration complexity estimate (low/medium/high)
+
+    ## Output Format
+
+    Each idea file should follow this structure:
+
+    \`\`\`markdown
+    # [Issue Type]: [Brief Description]
+
+    ## Current Structure
+
+    [List specific paths from affectedPaths]
+
+    ## Problem
+
+    [Description of why this is problematic]
+
+    ## Proposed Solution
+
+    [Suggested reorganization]
+
+    ## Migration Complexity
+
+    [Low/Medium/High with brief rationale]
+    \`\`\`
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - Explored the directory tree excluding standard build/tool directories
+    - Created idea files for all findings in \`.dust/ideas/\`
+    - Each idea includes specific paths, problem description, proposed solution, and complexity
+    - No changes to files outside \`.dust/\`
+  `;
+}
 function documentationDrift() {
   return dedent`
     # Documentation Drift
@@ -1680,6 +1756,110 @@ function factsVerification() {
     - No changes to files outside \`.dust/\`
   `;
 }
+function factsExpansion() {
+  return dedent`
+    # Facts Expansion
+
+    Review the codebase for significant facts that should be documented in \`.dust/facts/\`.
+
+    ${ideasHint}
+
+    ## Context
+
+    Facts capture how things work today, providing context for agents and contributors. However, not all significant aspects of the codebase are currently documented as facts. This creates gaps where agents working in specific areas may lack important context that isn't obvious from scanning code or having prior framework knowledge.
+
+    ## Applicability
+
+    This audit applies to all codebases. If \`.dust/facts/\` does not exist, the audit will identify initial facts to document.
+
+    ## Scope
+
+    Analyze the codebase for undocumented facts across these areas:
+
+    ### Architectural Decisions
+    - Separation of concerns patterns not enforced by directory structure
+    - Dependency flow rules (e.g., what can depend on what)
+    - Layer boundaries and their purposes
+    - Module initialization order requirements
+    - Plugin or extension mechanisms
+
+    ### Implementation Conventions
+    - Naming patterns for specific types of code (factories, builders, validators)
+    - Error handling conventions (when to throw vs return errors)
+    - Async/await patterns and Promise handling
+    - Resource cleanup patterns
+    - State management approaches
+
+    ### External Integration Points
+    - CLI command structure and parsing approach
+    - Event emission patterns
+    - File system conventions
+    - Process spawning patterns
+    - Network communication protocols
+
+    ### Performance Characteristics
+    - Known performance bottlenecks
+    - Caching strategies
+    - Lazy loading patterns
+    - Resource pooling approaches
+    - Optimization trade-offs
+
+    ### Historical Context
+    - Migration paths from previous approaches
+    - Deprecated patterns still present in legacy code
+    - Trade-offs made in past decisions
+    - Features that were removed and why
+
+    ## Analysis Approach
+
+    1. **Scan for patterns** - Look for repeated implementation patterns across multiple files
+    2. **Identify conventions** - Find coding conventions that aren't enforced by linters
+    3. **Review configuration** - Document configuration systems and their purposes
+    4. **Trace data flows** - Identify how data moves through the system
+    5. **Check existing facts** - Compare findings against what's already documented in \`.dust/facts/\`
+    6. **Filter for significance** - Only suggest facts that would genuinely help future agents (facts that aren't obvious from code inspection or general framework knowledge)
+
+    ## Significance Criteria
+
+    A fact is worth documenting if:
+    - It's not obvious from reading the code in isolation
+    - It represents a project-specific decision or convention
+    - Future agents would benefit from knowing it before making changes
+    - It documents framework patterns actually used in this project
+
+    ## Output Format
+
+    For each suggested fact, create an idea file in \`.dust/ideas/\` that includes:
+
+    ### Fact Title
+    A clear, concise title for the proposed fact.
+
+    ### Why This Matters
+    Explanation of why this fact would be valuable to document (what gaps it fills, what problems it prevents).
+
+    ### What to Document
+    Specific aspects to cover in the fact file.
+
+    ### Where to Look
+    File paths or code locations that demonstrate this fact.
+
+    ### Example Content
+    A sketch of what the fact file might contain (2-3 sentences showing the style and key points).
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - Analyzed codebase for undocumented patterns across all specified areas
+    - Compared findings against existing facts in \`.dust/facts/\`
+    - Applied significance criteria to filter suggestions
+    - Created idea files for each suggested fact with complete metadata
+    - Each idea includes: fact title, why it matters, what to document, where to look, example content
+    - No changes to files outside \`.dust/\`
+  `;
+}
 function feedbackLoopSpeed() {
   return dedent`
     # Feedback Loop Speed
@@ -1690,7 +1870,7 @@ function feedbackLoopSpeed() {
 
     ## Context
 
-    The [Fast Feedback Loops](../principles/fast-feedback-loops.md) principle emphasizes that the primary feedback loop—write code, run checks, see results—should be as fast as possible. 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.
+    The primary feedback loop—write code, run checks, see results—should be as fast as possible. 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 audit focuses specifically on measuring the development feedback loop speed to help identify which checks consume the most time.
 
@@ -2136,6 +2316,223 @@ function ideasFromPrinciples() {
     - No changes to files outside \`.dust/\`
   `;
 }
+function incidentalTestDetails() {
+  return dedent`
+    # Incidental Test Details
+
+    Identify tests with overly specific data and other incidental details that obscure test intent.
+
+    ${ideasHint}
+
+    ## Context
+
+    Test clarity suffers when tests include incidental complexity — details that aren't relevant to what's being tested. Overly specific data, unused properties, magic numbers, excessive mocking, and complex nested structures all make tests harder to understand and maintain. This audit identifies these patterns as candidates for simplification.
+
+    The audit flags patterns for review without making judgments about whether they're necessary in specific cases. Some tests legitimately need complex setup to verify specific behaviors; the goal is to surface candidates so agents can evaluate each case and simplify where appropriate.
+
+    ## Guidance
+
+    ### Readable Test Data
+
+    Test data setup should use natural structures that mirror what they represent.
+
+    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.
+
+    Prefer literal structures that visually match the domain:
+
+    \`\`\`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']),
+    })
+
+    // 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
+
+    ### 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."
+
+    Collapse multiple partial assertions into one comprehensive assertion:
+
+    \`\`\`javascript
+    // Fragmented — each failure is a narrow keyhole
+    expect(result.name).toBe("Alice");
+    expect(result.age).toBe(30);
+    expect(result.role).toBe("admin");
+
+    // Whole — a failure diff tells the full story
+    expect(result).toEqual({
+      name: "Alice",
+      age: 30,
+      role: "admin",
+    });
+    \`\`\`
+
+    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.
+
+    ### Self-Diagnosing Tests
+
+    When a big test fails, it should be self-evident how to diagnose and fix the failure.
+
+    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.
+
+    Anti-patterns:
+
+    **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)
+
+    // Good: shows the actual event types on failure
+    expect(events.map(e => e.type)).toContain('check-passed')
+    \`\`\`
+
+    **Length-only assertions** — checking count without showing contents:
+    \`\`\`javascript
+    // Bad: "expected 2, received 0" — what requests were captured?
+    expect(requests.length).toBe(2)
+
+    // Good: shows the actual requests on failure
+    expect(requests).toHaveLength(2)  // vitest shows the array
+    \`\`\`
+
+    **Silent guards** — using \`if\` where an assertion belongs:
+    \`\`\`javascript
+    // Bad: silently passes when settings is undefined
+    if (settings) {
+      expect(JSON.parse(settings).key).toBeDefined()
+    }
+
+    // Good: fails explicitly if settings is missing
+    expect(settings).toBeDefined()
+    const parsed = JSON.parse(settings!)
+    expect(parsed.key).toBeDefined()
+    \`\`\`
+
+    ### 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.
+
+    ## Scope
+
+    Search for test files and analyze them for clarity issues:
+
+    1. **Test files** - Files matching \`*.test.ts\`, \`*.test.js\`, \`*.spec.ts\`, \`*.spec.js\`
+       - Include unit, integration, and system tests
+       - Exclude exploratory test files
+
+    2. **Patterns to identify**:
+       - Object literals with unused properties in test setup
+       - Magic numbers without semantic meaning
+       - Excessive mock/stub setup
+       - Complex nested structures where simpler ones would suffice
+       - Brittle string assertions coupled to formatting
+       - Boolean flattening (testing \`.toBe(true)\` instead of showing actual values)
+       - Length-only assertions (testing \`.length\` instead of \`.toHaveLength()\`)
+       - Silent guards (using \`if\` where assertions belong)
+
+    ## Analysis Steps
+
+    1. **Find test files**
+       - Search for \`**/*.test.ts\`, \`**/*.test.js\`, \`**/*.spec.ts\`, \`**/*.spec.js\`
+       - Filter out exploratory tests
+
+    2. **Analyze each test file**
+       - Look for object literals in test setup with properties that aren't used in assertions
+       - Identify numeric literals that lack semantic meaning (e.g., \`42\`, \`123\` without explaining what they represent)
+       - Count mock/stub setup lines relative to actual test logic
+       - Check for deeply nested test data structures (3+ levels)
+       - Find string assertions that compare exact formatting (spaces, newlines, etc.) rather than semantic content
+       - Detect boolean flattening patterns (\`.some()\`, \`.every()\`, \`.includes()\` followed by \`.toBe(true/false)\`)
+       - Find length checks using \`.length\` property instead of \`.toHaveLength()\`
+       - Locate conditional logic in tests (\`if\` statements) that should be assertions
+
+    3. **Create ideas for issues found**
+       - Group issues by test file
+       - For each file with issues, create an idea file documenting:
+         - Test file path
+         - List of patterns found with line numbers
+         - Pattern categories
+         - Current problematic patterns
+         - Recommended refactoring approaches
+
+    ## Output Format
+
+    For each test file with clarity issues, create an idea file with:
+
+    ### Title
+    "Simplify test data in [filename]"
+
+    ### Content Structure
+    \`\`\`markdown
+    # Simplify test data in [filename]
+
+    The test file \`[path]\` contains incidental details that obscure test intent.
+
+    ## Issues Found
+
+    ### [Pattern Name] (line X)
+    - **Current**: \`[code snippet]\`
+    - **Issue**: [explanation of how this obscures intent]
+    - **Recommendation**: [specific simplification guidance]
+
+    [Repeat for each issue]
+    \`\`\`
+
+    ## Applicability
+
+    This audit applies to codebases with test files. If the codebase has no test files (\`*.test.ts\`, \`*.spec.js\`, etc.), document that finding and skip the detailed analysis.
+
+    ## Focus
+
+    This audit focuses purely on test clarity — whether tests clearly communicate intent. It does not evaluate test performance or execution speed.
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - Searched for all test files in the codebase
+    - Analyzed test files for incidental complexity patterns
+    - Identified tests with unused properties in setup data
+    - Found magic numbers lacking semantic meaning
+    - Flagged excessive mock/stub setup
+    - Located complex nested structures
+    - Detected brittle string assertions
+    - Found boolean flattening patterns
+    - Located length-only assertions
+    - Identified silent guards (if statements in tests)
+    - Created idea files for each test file with findings
+    - Each idea includes: file path, issues with line numbers, pattern categories, current patterns, recommendations
+    - No changes to files outside \`.dust/\`
+  `;
+}
 function commitReview() {
   return dedent`
     # Commit Review
@@ -2146,7 +2543,13 @@ function commitReview() {
 
     ## Scope
 
-    Analyze commits since the last commit-review audit (check \`.dust/done/\` for previous runs). Focus on these signals:
+    Determine which commits to analyze:
+
+    1. Check VCS history for a prior commit-review run: \`git log --grep="Audit: Commit Review" -1 --format=%H\`
+    2. If found, analyze commits since that commit
+    3. If not found, analyze the last 20 commits as a fallback
+
+    Focus on these signals:
 
     1. **File churn** - Files modified frequently across multiple commits may have unclear responsibilities or be accumulating technical debt
     2. **Size growth** - Files that have grown significantly may benefit from decomposition
@@ -2492,6 +2895,168 @@ function slowTests() {
     - No changes to files outside \`.dust/\`
   `;
 }
+function overAbstraction() {
+  return dedent`
+    # Over-Abstraction
+
+    Identify violations of the "reasonably-dry" principle where code has been over-engineered with excessive abstraction.
+
+    ${ideasHint}
+
+    ## Scope
+
+    Detect these over-abstraction patterns:
+
+    1. **Single-use abstractions** - Interfaces, base classes, or utility functions used in only one place
+    2. **Deep inheritance hierarchies** - Classes extending more than 2 levels deep
+    3. **Premature generalization** - Parameters always used with the same value, unused options/flags
+    4. **Excessive indirection** - Multiple layers of wrappers adding no value
+
+    ## Analysis Steps
+
+    ### 1. Find Single-Use Abstractions
+
+    Search for abstractions that are only used once:
+
+    1. **Interfaces with one implementation**
+       - Search for \`interface\` declarations
+       - Check if each interface has only one implementing class
+       - Flag interfaces that exist solely for testing (can be replaced with the concrete type)
+
+    2. **Base classes with one subclass**
+       - Search for \`abstract class\` or classes used as base classes
+       - Count implementations extending each base class
+       - Flag base classes with only one subclass
+
+    3. **Utility functions called once**
+       - Search for exported utility functions
+       - Check call sites - if only called from one location, it's over-abstraction
+       - Consider inlining single-use utilities
+
+    4. **Generic types with one concrete usage**
+       - Find generic type parameters: \`<T>\`, \`<TData>\`, etc.
+       - Check if T is always the same type at all call sites
+       - Flag generics that could be concrete types
+
+    ### 2. Detect Deep Inheritance Hierarchies
+
+    Find inheritance chains longer than 2 levels:
+
+    1. Search for \`extends\` keywords in class declarations
+    2. Build inheritance tree for each class
+    3. Flag chains deeper than 2 (A extends B extends C extends D...)
+    4. Respect framework conventions (don't flag React.Component, etc.)
+
+    ### 3. Identify Premature Generalization
+
+    Look for flexibility that's never used:
+
+    1. **Always-same parameter values**
+       - Find function parameters
+       - Check all call sites - if always the same value, it's not needed
+       - Flag parameters that could be constants or removed
+
+    2. **Unused configuration options**
+       - Search for configuration objects/interfaces
+       - Check which options are actually used
+       - Flag options that are never set or always default
+
+    3. **Unused function parameters**
+       - Find parameters that aren't referenced in function bodies
+       - Flag as candidates for removal
+
+    ### 4. Find Excessive Indirection
+
+    Detect wrapper chains that add no value:
+
+    1. **Delegation chains**
+       - Search for functions that only call another function
+       - Flag wrappers that don't add logic, just forward calls
+       - Example: \`function foo(x) { return bar(x) }\`
+
+    2. **Proxy patterns without behavior**
+       - Find classes that wrap another class
+       - Check if wrapper adds any logic beyond forwarding
+       - Flag pure proxies
+
+    3. **Middleware without transformation**
+       - Look for middleware/interceptor patterns
+       - Check if they modify data or just pass through
+       - Flag pass-through middleware
+
+    ## Output Format
+
+    For each over-abstraction found, create an idea file in \`.dust/ideas/\` with:
+
+    \`\`\`markdown
+    # Over-Abstraction: [Type] in [Location]
+
+    ## Type
+
+    [Single-use | Deep hierarchy | Premature generalization | Excessive indirection]
+
+    ## Location
+
+    \`\`\`
+    [file path]:[line number]
+    \`\`\`
+
+    ## Description
+
+    [What the abstraction is]
+
+    ## Problem
+
+    [Why this is over-abstraction - complexity without benefit]
+
+    ## Usage Analysis
+
+    - **Times used**: [count]
+    - **Variation in usage**: [how different are the use cases]
+    - **Complexity cost**: [lines of code, indirection levels, etc.]
+
+    ## Suggested Simplification
+
+    [How to remove or reduce this abstraction]
+
+    ## Impact
+
+    [Lines of code saved, reduced complexity, improved clarity]
+    \`\`\`
+
+    ## Special Considerations
+
+    1. **Framework conventions** - Don't flag patterns mandated by frameworks:
+       - React: Component base classes, hooks patterns
+       - Express: Middleware signatures
+       - Testing: Test base classes, fixture patterns
+
+    2. **Library boundaries** - Public API abstractions may be justified even if internal usage is simple
+
+    3. **Test code** - Apply the same standards to test code as production code
+
+    4. **Context depth thresholds**:
+       - Deep hierarchies (>2 levels) make understanding difficult
+       - Wrapper chains (>2 levels) obscure actual behavior
+       - Generic parameters should have multiple concrete usages
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - Searched for single-use interfaces, base classes, and utility functions
+    - Identified deep inheritance hierarchies (>2 levels)
+    - Found parameters always used with the same value
+    - Detected unused configuration options
+    - Located excessive wrapper chains and delegation
+    - Respected framework conventions (didn't flag framework-mandated patterns)
+    - Created idea files for each over-abstraction found
+    - Each idea includes usage analysis and simplification suggestions
+    - No changes to files outside \`.dust/\`
+  `;
+}
 function primitiveObsession() {
   return dedent`
     # Primitive Obsession
@@ -2763,7 +3328,7 @@ function testAssertions() {
 
     ## Background
 
-    The [Comprehensive Assertions](../principles/comprehensive-assertions.md) principle covers asserting whole objects rather than fragments. The [Self-Diagnosing Tests](../principles/self-diagnosing-tests.md) principle covers making failure messages informative. This audit addresses complementary assertion quality signals not covered by existing principles.
+    Comprehensive assertions (asserting the whole, not the parts) provide richer failure diagnostics. Self-diagnosing tests ensure that failures reveal enough context to guide a fix without re-running. This audit addresses complementary assertion quality signals not covered by those principles.
 
     ## Scope
 
@@ -2822,7 +3387,7 @@ function testAssertions() {
     - Require test updates for unrelated changes
     - Obscure what the test is actually verifying
 
-    This works in tension with [Comprehensive Assertions](../principles/comprehensive-assertions.md). Let context determine the balance:
+    This works in tension with comprehensive assertions (asserting the whole, not the parts). Let context determine the balance:
     - Public API contracts → comprehensive assertions
     - Internal implementation tests → precise assertions
     - Snapshot tests → consider \`toMatchSnapshot()\` with care
@@ -2849,7 +3414,7 @@ function testAssertions() {
 
     Tests should ideally verify one behavior or scenario. When a test has multiple unrelated assertions, a failure in the first masks all subsequent ones.
 
-    This does not mean "one \`expect\` call per test". A single logical assertion may require multiple \`expect\` calls to express (especially for complex state). The [Comprehensive Assertions](../principles/comprehensive-assertions.md) principle often allows collapsing multiple calls into one whole-object assertion.
+    This does not mean "one \`expect\` call per test". A single logical assertion may require multiple \`expect\` calls to express (especially for complex state). Comprehensive assertions (asserting the whole, not the parts) often allow collapsing multiple calls into one whole-object assertion.
 
     The anti-pattern to avoid:
     \`\`\`javascript
@@ -3012,6 +3577,95 @@ function loggingAndTraceability() {
     - No changes to files outside \`.dust/\`
   `;
 }
+function testDeterminism() {
+  return dedent`
+    # Test Determinism
+
+    Audit unit tests for non-deterministic patterns that cause tests to produce inconsistent results across different environments or executions.
+
+    ${ideasHint}
+
+    ## Context
+
+    Tests must produce the same result regardless of where they run. Non-deterministic tests undermine confidence in CI, make debugging harder, and waste developer time chasing phantom failures. This audit identifies patterns that introduce non-determinism: time dependencies, randomness, environment variable access, filesystem operations, real timers, and platform-specific behavior.
+
+    ## Scope
+
+    Search for unit test files and analyze them for determinism issues:
+
+    1. **Unit test files** - Files matching \`*.test.ts\`, \`*.test.js\`, \`*.spec.ts\`, \`*.spec.js\`
+       - Exclude system test files (files containing 'system-test' or in 'system-tests/' directories)
+       - Exclude exploratory test files
+
+    2. **Issue categories to detect**:
+       - Time dependencies (\`Date.now()\`, \`new Date()\`) — should use dependency injection or stubbed time
+       - Randomness (\`Math.random()\`, \`crypto.randomBytes()\`, \`randomUUID()\`) — should use seeded random or injection
+       - Environment variables (\`process.env.VARIABLE\` without \`stubEnv\`) — should use \`stubEnv()\` or pass env as a parameter
+       - Filesystem operations (file reads/writes in unit tests) — should use in-memory filesystem or ensure cleanup
+       - Real timers (\`setTimeout\`, \`setInterval\` without fake timers) — should use \`vi.useFakeTimers()\`
+       - Platform-specific code (\`process.platform\`, \`__dirname\`, \`os.EOL\`) — should use dependency injection or normalize paths
+
+    ## Analysis Steps
+
+    1. **Find unit test files**
+       - Search for \`**/*.test.ts\`, \`**/*.test.js\`, \`**/*.spec.ts\`, \`**/*.spec.js\`
+       - Filter out system test files and exploratory tests
+
+    2. **Analyze each test file**
+       - Read the file content
+       - Look for the patterns listed above
+       - Note: patterns used inside stub/mock setups (\`vi.fn()\`, \`vi.mock()\`, \`vi.spyOn()\`), function parameter type annotations, or \`stubEnv()\` calls are not issues — they represent proper test practices
+
+    3. **Create ideas for issues found**
+       - Group issues by test file
+       - For each file with issues, create an idea file documenting:
+         - Test file path
+         - List of issues with line numbers
+         - Issue categories
+         - Current problematic patterns
+         - Recommended refactoring approaches
+
+    ## Output Format
+
+    For each test file with determinism issues, create an idea file with:
+
+    ### Title
+    "Refactor [filename] for test determinism"
+
+    ### Content Structure
+    \`\`\`markdown
+    # Refactor [filename] for test determinism
+
+    The test file \`[path]\` contains non-deterministic patterns that should be refactored.
+
+    ## Issues Found
+
+    ### [Category Name] (line X)
+    - **Pattern**: \`[code snippet]\`
+    - **Issue**: [explanation of why this is non-deterministic]
+    - **Recommendation**: [specific refactoring guidance]
+
+    [Repeat for each issue]
+    \`\`\`
+
+    ## Applicability
+
+    This audit applies to codebases with unit tests. If the codebase has no unit test files (\`*.test.ts\`, \`*.spec.js\`, etc.), document that finding and skip the detailed analysis.
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - Searched for unit test files (\`*.test.ts\`, \`*.test.js\`, \`*.spec.ts\`, \`*.spec.js\`)
+    - Excluded system test and exploratory test files
+    - Analyzed each unit test file for determinism issues
+    - Created idea files for test files containing determinism issues
+    - Each idea includes specific line numbers, patterns, and refactoring guidance
+    - No changes to files outside \`.dust/\`
+  `;
+}
 function testPyramid() {
   return dedent`
     # Test Pyramid
@@ -3380,7 +4034,7 @@ function ciDevelopmentParity() {
     2. **Wasted cycles** - Developers push code that passes locally only to have CI fail
     3. **Agent confusion** - AI agents rely on consistent feedback; discrepancies trigger incorrect debugging paths
 
-    The [Reproducible Checks](../principles/reproducible-checks.md) principle ensures the same checks run everywhere.
+    Every check must produce the same result regardless of who runs it, when, or on what machine.
 
     ## Scope
 
@@ -3470,7 +4124,7 @@ function ciDevelopmentParity() {
 
     - Developers may push code that passes locally but fails CI on other checks
     - CI provides no coverage for [check category]
-    - The [Stop the Line](../principles/stop-the-line.md) principle is violated - problems aren't caught before merge
+    - Problems aren't caught before merge—any worker should halt and fix a problem the moment they detect it
 
     ## Suggested Fix
 
@@ -3494,7 +4148,7 @@ function ciDevelopmentParity() {
     ## Impact
 
     - Developers don't get [check category] feedback until CI runs
-    - [Fast Feedback Loops](../principles/fast-feedback-loops.md) are broken - local checks give incomplete picture
+    - Fast feedback loops are broken—local checks give incomplete picture
     - Agents may make changes that pass local checks but fail CI
 
     ## Suggested Fix
@@ -3532,7 +4186,7 @@ function commitMessageQuality() {
 
     ## Context
 
-    The [Traceable Decisions](../principles/traceable-decisions.md) principle emphasizes that commit history should explain why changes were made. Good commit messages help agents understand project history and make better decisions. This audit evaluates commit message quality itself, not the code changes.
+    Commit history should explain why changes were made, not just what changed. Good commit messages help agents understand project history and make better decisions. This audit evaluates commit message quality itself, not the code changes.
 
     ## Scope
 
@@ -3673,20 +4327,14 @@ function commitMessageQuality() {
   `;
 }
 function suggestAudits() {
-  const auditList = Object.entries(stockAuditFunctions).filter(([name]) => name !== "suggest-audits").toSorted(([a], [b]) => a.localeCompare(b)).map(([name, render]) => {
-    const template = render();
-    const description = extractOpeningSentence(template);
-    return `- **${name}**: ${description}`;
-  }).join(`
-`);
-  let content = dedent`
+  return dedent`
     # Suggest Audits
 
     Analyze recent commits and create tasks for relevant audits to run.
 
     ## Context
 
-    This audit examines recent commit history and suggests which stock audits would be valuable based on what changed. Rather than manually selecting audits, this provides an automated way to maintain codebase health by matching recent work to appropriate audits.
+    This audit examines recent commit history and suggests which audits would be valuable based on what changed. Rather than manually selecting audits, this provides an automated way to maintain codebase health by matching recent work to appropriate audits.
 
     ## Commit Range
 
@@ -3698,21 +4346,17 @@ function suggestAudits() {
 
     ## Available Audits
 
-  `;
-  content += `
-
-` + auditList + `
-`;
-  content += dedent`
+    Run \`dust audit\` to list all available audits (including both stock audits and any repository-specific audits configured in \`.dust/config/audits/\`). This will show the audit name and description for each available audit.
 
     ## Analysis Steps
 
-    1. **Gather commits** - Get the list of commits in the determined range with their messages and changed files
-    2. **Categorize changes** - Group commits by the type of work (features, fixes, refactoring, tests, docs, config)
-    3. **Match to audits** - For each relevant audit, explain why recent changes make it valuable:
+    1. **List audits** - Run \`dust audit\` to get the complete list of available audits with descriptions
+    2. **Gather commits** - Get the list of commits in the determined range with their messages and changed files
+    3. **Categorize changes** - Group commits by the type of work (features, fixes, refactoring, tests, docs, config)
+    4. **Match to audits** - For each relevant audit, explain why recent changes make it valuable:
        - What specific commits or file changes triggered the suggestion?
        - What might the audit uncover given this context?
-    4. **Create tasks** - For each suggested audit, create a task file in \`.dust/tasks/\`
+    5. **Create tasks** - For each suggested audit, create a task file in \`.dust/tasks/\`
 
     ## Output
 
@@ -3761,7 +4405,6 @@ function suggestAudits() {
     - Each task explains why the audit is valuable given recent changes
     - No changes to files outside \`.dust/\`
   `;
-  return content;
 }
 var stockAuditFunctions = {
   "agent-developer-experience": agentDeveloperExperience,
@@ -3777,7 +4420,9 @@ var stockAuditFunctions = {
   "data-access-review": dataAccessReview,
   "dead-code": deadCode,
   "design-patterns": designPatterns,
+  "directory-hierarchy": directoryHierarchy,
   "error-handling": errorHandling,
+  "facts-expansion": factsExpansion,
   "facts-verification": factsVerification,
   "feedback-loop-speed": feedbackLoopSpeed,
   "flaky-tests": flakyTests,
@@ -3785,7 +4430,9 @@ var stockAuditFunctions = {
   "commit-review": commitReview,
   "ideas-from-principles": ideasFromPrinciples,
   "idiomatic-style": idiomaticStyle,
+  "incidental-test-details": incidentalTestDetails,
   "logging-and-traceability": loggingAndTraceability,
+  "over-abstraction": overAbstraction,
   "primitive-obsession": primitiveObsession,
   "repository-context": repositoryContext,
   "security-review": securityReview,
@@ -3794,6 +4441,7 @@ var stockAuditFunctions = {
   "stale-ideas": staleIdeas,
   "suggest-audits": suggestAudits,
   "test-assertions": testAssertions,
+  "test-determinism": testDeterminism,
   "test-pyramid": testPyramid,
   "ubiquitous-language": ubiquitousLanguage,
   "ux-audit": uxAudit
@@ -4022,7 +4670,7 @@ async function loadStoredToken(fileSystem, homeDir) {
     const data = JSON.parse(content);
     return typeof data.token === "string" ? data.token : null;
   } catch (error) {
-    if (error.code === "ENOENT") {
+    if (isErrorCode(error, "ENOENT")) {
       return null;
     }
     throw error;
@@ -4038,7 +4686,7 @@ async function clearToken(fileSystem, homeDir) {
   try {
     await fileSystem.writeFile(path, "{}");
   } catch (error) {
-    if (error.code === "ENOENT") {
+    if (isErrorCode(error, "ENOENT")) {
       return;
     }
     throw error;
@@ -5269,6 +5917,8 @@ function buildImplementationInstructions(bin, hooksInstalled, taskTitle, taskPat
     steps.push(`${step}. Run \`${bin} check\` to verify the project is in a good state`);
     step++;
   }
+  steps.push(`${step}. If the task file contains Principles and Guidance sections, read and follow them before implementing changes`);
+  step++;
   steps.push(`${step}. Implement the task`);
   step++;
   if (!hooksInstalled) {
@@ -5934,7 +6584,10 @@ function createWireEventSender(eventsUrl, sessionId, postEvent, onError, getAgen
 
 // lib/loop/iteration.ts
 var log2 = createLogger("dust:loop:iteration");
-var DUST_QUICK_REFERENCE = `## Dust Quick Reference
+function DUST_QUICK_REFERENCE(dustCommand) {
+  return `## Dust Quick Reference
+
+Dust is a CLI tool for managing development workflows through markdown artifacts. In this environment, run dust commands using: \`${dustCommand}\` (this might be \`dust\`, \`bunx dust\`, \`npx dust\`, or another prefix depending on how dust is installed).
 
 Dust stores project context in \`.dust/\` as markdown artifacts. Use these commands to explore:
 
@@ -5944,6 +6597,7 @@ Dust stores project context in \`.dust/\` as markdown artifacts. Use these comma
 - \`dust help\` — see all available commands
 
 Use dust commands instead of manually searching \`.dust/\` directories.`;
+}
 function getEnvironmentContext(cwd) {
   return {
     machineName: os.hostname(),
@@ -6158,7 +6812,7 @@ async function runOneIteration(dependencies, loopDependencies, onLoopEvent, onAg
   }
   const taskContent = await fileSystem.readFile(`${context.cwd}/${task.path}`);
   const instructions = buildImplementationInstructions(settings.dustCommand, hooksInstalled, task.title ?? undefined, task.path, settings.installCommand, true);
-  const taskPrompt = buildTaskPrompt(task.path, taskContent, instructions, toolsSection, options.branch);
+  const taskPrompt = buildTaskPrompt(task.path, taskContent, instructions, toolsSection, settings.dustCommand, options.branch);
   let originalRemoteUrl;
   if (docker?.gitProxyUrl) {
     try {
@@ -6220,7 +6874,7 @@ Please resolve this issue. Common approaches:
 
 Make sure the repository is in a clean state and synced with remote before finishing.`;
 }
-function buildTaskPrompt(taskPath, taskContent, instructions, toolsSection, branch) {
+function buildTaskPrompt(taskPath, taskContent, instructions, toolsSection, dustCommand, branch) {
   const suffix = toolsSection ? `
 ${toolsSection}` : "";
   const branchContext = branch ? `You are working on the \`${branch}\` branch.
@@ -6232,7 +6886,7 @@ ${toolsSection}` : "";
 ${taskContent}
 ----------
 
-${DUST_QUICK_REFERENCE}
+${DUST_QUICK_REFERENCE(dustCommand)}
 
 ## How to implement the task
 
@@ -10097,7 +10751,7 @@ async function validateContentDirectoryFiles(dirPath, fileSystem) {
   try {
     entries = await fileSystem.readdir(dirPath);
   } catch (error) {
-    if (error.code === "ENOENT") {
+    if (isErrorCode(error, "ENOENT")) {
       return [];
     }
     throw error;
@@ -10133,7 +10787,7 @@ async function validateDirectoryStructure(dustPath, fileSystem) {
   try {
     entries = await fileSystem.readdir(dustPath);
   } catch (error) {
-    if (error.code === "ENOENT") {
+    if (isErrorCode(error, "ENOENT")) {
       return [];
     }
     throw error;
@@ -10179,7 +10833,7 @@ async function validateDirectoryStructure(dustPath, fileSystem) {
   try {
     configEntries = await fileSystem.readdir(configPath);
   } catch (error) {
-    if (error.code === "ENOENT") {
+    if (isErrorCode(error, "ENOENT")) {
       return violations;
     }
     throw error;
@@ -10617,7 +11271,7 @@ async function parseArtifacts(fileSystem, dustPath) {
   try {
     rootEntries = await fileSystem.readdir(dustPath);
   } catch (error) {
-    if (error.code === "ENOENT") {
+    if (isErrorCode(error, "ENOENT")) {
       rootEntries = [];
     } else {
       throw error;
@@ -10631,7 +11285,7 @@ async function parseArtifacts(fileSystem, dustPath) {
     try {
       content = await fileSystem.readFile(filePath);
     } catch (error) {
-      if (error.code === "ENOENT") {
+      if (isErrorCode(error, "ENOENT")) {
         continue;
       }
       throw error;
@@ -10647,7 +11301,7 @@ async function parseArtifacts(fileSystem, dustPath) {
     try {
       entries = await fileSystem.readdir(dirPath);
     } catch (error) {
-      if (error.code === "ENOENT") {
+      if (isErrorCode(error, "ENOENT")) {
         continue;
       }
       throw error;
@@ -10675,7 +11329,7 @@ async function parseArtifacts(fileSystem, dustPath) {
   try {
     auditEntries = await fileSystem.readdir(auditsPath);
   } catch (error) {
-    if (error.code === "ENOENT") {
+    if (isErrorCode(error, "ENOENT")) {
       auditEntries = [];
     } else {
       throw error;
@@ -10689,7 +11343,7 @@ async function parseArtifacts(fileSystem, dustPath) {
     try {
       content = await fileSystem.readFile(filePath);
     } catch (error) {
-      if (error.code === "ENOENT") {
+      if (isErrorCode(error, "ENOENT")) {
         continue;
       }
       throw error;
@@ -10774,7 +11428,7 @@ async function safeReadFile(fileSystem, filePath) {
   try {
     return await fileSystem.readFile(filePath);
   } catch (error) {
-    if (error.code === "ENOENT") {
+    if (isErrorCode(error, "ENOENT")) {
       return null;
     }
     throw error;
@@ -12662,7 +13316,7 @@ async function init(dependencies) {
     await fileSystem.writeFile(`${dustPath}/facts/use-dust-for-planning.md`, USE_DUST_FACT, { flag: "wx" });
     dustDirCreated = true;
   } catch (error) {
-    if (error.code !== "EEXIST") {
+    if (!isErrorCode(error, "EEXIST")) {
       throw error;
     }
   }
@@ -12671,7 +13325,7 @@ async function init(dependencies) {
     await fileSystem.writeFile(`${dustPath}/config/settings.json`, `${JSON.stringify(settings, null, 2)}
 `, { flag: "wx" });
   } catch (error) {
-    if (error.code !== "EEXIST") {
+    if (!isErrorCode(error, "EEXIST")) {
       throw error;
     }
   }
@@ -12690,7 +13344,7 @@ async function init(dependencies) {
     });
     context.stdout(`${colors.green}\uD83D\uDCC4 Created${colors.reset} ${colors.cyan}CLAUDE.md${colors.reset} with agent instructions`);
   } catch (error) {
-    if (error.code === "EEXIST") {
+    if (isErrorCode(error, "EEXIST")) {
       context.stdout(`${colors.yellow}⚠️  Warning:${colors.reset} ${colors.cyan}CLAUDE.md${colors.reset} already exists. Consider adding: ${colors.dim}"${agentInstruction}"${colors.reset}`);
     } else {
       throw error;
@@ -12703,7 +13357,7 @@ async function init(dependencies) {
     });
     context.stdout(`${colors.green}\uD83D\uDCC4 Created${colors.reset} ${colors.cyan}AGENTS.md${colors.reset} with agent instructions`);
   } catch (error) {
-    if (error.code === "EEXIST") {
+    if (isErrorCode(error, "EEXIST")) {
       context.stdout(`${colors.yellow}⚠️  Warning:${colors.reset} ${colors.cyan}AGENTS.md${colors.reset} already exists. Consider adding: ${colors.dim}"${agentInstruction}"${colors.reset}`);
     } else {
       throw error;
@@ -13331,7 +13985,7 @@ async function scanMarkdownFiles(glob, dirPath) {
     }
     return files;
   } catch (error) {
-    if (error.code === "ENOENT") {
+    if (isErrorCode(error, "ENOENT")) {
       return [];
     }
     throw error;