@joshski/dust 0.1.106 → 0.1.108

package/.dust/principles/keep-unit-tests-pure.md

@@ -1,25 +0,0 @@
-# Keep Unit Tests Pure
-
-Unit tests (those run very frequently as part of a tight feedback loop) should be pure and side-effect free. A test is **not** a unit test if it:
-
-- Accesses a database
-- Communicates over a network
-- Touches the file system
-- Cannot run concurrently with other tests
-- Requires special environment setup
-
-"Unit tests" here means tests run frequently during development — not system tests, which intentionally exercise the full stack including I/O. Pure unit tests exercise only business logic, not infrastructure.
-
-The value of pure unit tests is that they are fast, deterministic, and isolate business logic from infrastructure concerns. When unit tests pass but integration or system tests fail, developers can immediately narrow the problem to the boundary layer — a diagnostic "binary chop" that accelerates debugging.
-
-## Migration Guidance
-
-Where existing tests are impure (e.g. they spawn processes, write temporary files, or make network calls), prefer converting them to use in-memory alternatives — stubs, fakes, or dependency-injected doubles — rather than leaving them as-is. Opportunistic migration is fine; a big-bang rewrite is not required.
-
-## Parent Principle
-
-- [Make Changes with Confidence](make-changes-with-confidence.md)
-
-## Sub-Principles
-
-- (none)

package/.dust/principles/lightweight-planning.md

@@ -1,16 +0,0 @@
-# Lightweight Planning
-
-Dust aims to be a minimal, low-overhead planning system that stays relevant over time.
-
-Planning artifacts are simple markdown files that live alongside code. Ideas are intentionally vague until implementation is imminent. Tasks are small and completable in single commits. Facts document current reality rather than aspirational states.
-
-The system avoids the staleness problem by deferring detail until the last responsible moment and deleting completed work rather than archiving it.
-
-## Parent Principle
-
-- [Human-AI Collaboration](human-ai-collaboration.md)
-
-## Sub-Principles
-
-- [Task-First Workflow](task-first-workflow.md)
-- [Some Big Design Up Front](some-big-design-up-front.md)

package/.dust/principles/lint-everything.md

@@ -1,19 +0,0 @@
-# Lint Everything
-
-Prefer static analysis over runtime checks. Every error caught by a linter is an error that never reaches tests, and every error caught by tests is an error that never reaches production.
-
-Lint markdown, lint types, lint formatting. If it can be checked statically, check it. Linters are fast, deterministic, and catch entire categories of bugs before code even runs.
-
-This project lints:
-- TypeScript (type checking and style)
-- Markdown (broken links, required sections)
-- Task files (structure validation)
-- Principle hierarchy (parent/child consistency)
-
-## Parent Principle
-
-- [Make Changes with Confidence](make-changes-with-confidence.md)
-
-## Sub-Principles
-
-(none)

package/.dust/principles/maintainable-codebase.md

@@ -1,21 +0,0 @@
-# Maintainable Codebase
-
-The dust codebase should be easy to understand, modify, and extend.
-
-This principle governs how we develop and maintain dust itself, separate from the principles that describe what dust offers its users. A well-maintained codebase enables rapid iteration, reduces bugs, and makes contributions easier.
-
-## Parent Principle
-
-- [Agentic Flow State](agentic-flow-state.md)
-
-## Sub-Principles
-
-- [Make Changes with Confidence](make-changes-with-confidence.md)
-- [Minimal Dependencies](minimal-dependencies.md)
-- [Intuitive Directory Structure](intuitive-directory-structure.md)
-- [Repository Hygiene](repository-hygiene.md)
-- [Naming Matters](naming-matters.md)
-- [Reasonably DRY](reasonably-dry.md)
-- [Make the Change Easy](make-the-change-easy.md)
-- [Boy Scout Rule](boy-scout-rule.md)
-- [Broken Windows](broken-windows.md)

package/.dust/principles/make-changes-with-confidence.md

@@ -1,23 +0,0 @@
-# Make Changes with Confidence
-
-Developers should be able to modify code without fear of breaking existing behavior.
-
-Tests, type checking, and other automated verification enable safe refactoring and evolution of the codebase. When changes break something, fast feedback identifies the problem before it spreads. This confidence encourages continuous improvement rather than fragile, stagnant code.
-
-## Parent Principle
-
-- [Maintainable Codebase](maintainable-codebase.md)
-
-## Sub-Principles
-
-- [Comprehensive Assertions](comprehensive-assertions.md)
-- [Decoupled Code](decoupled-code.md)
-- [Fast Feedback](fast-feedback.md)
-- [Lint Everything](lint-everything.md)
-- [Readable Test Data](readable-test-data.md)
-- [Reproducible Checks](reproducible-checks.md)
-- [Stop the Line](stop-the-line.md)
-- [Keep Unit Tests Pure](keep-unit-tests-pure.md)
-- [Test Isolation](test-isolation.md)
-- [Self-Diagnosing Tests](self-diagnosing-tests.md)
-- [Unit Test Coverage](unit-test-coverage.md)

package/.dust/principles/make-the-change-easy.md

@@ -1,15 +0,0 @@
-# Make the Change Easy
-
-For each desired change, make the change easy, then make the easy change.
-
-This principle, articulated by Kent Beck, recognizes that the hardest part of a change is often not the change itself but the state of the code receiving it. When code resists a change, the right response is to first refactor until the change becomes straightforward, and only then make it. The warning - "this may be hard" - acknowledges that preparing the ground takes real effort, but the result is a change that fits naturally rather than one forced in against the grain.
-
-Work that supports this principle includes refactoring before feature work, improving abstractions that make a category of changes simpler, and resisting the urge to bolt changes onto code that isn't ready for them.
-
-## Parent Principle
-
-- [Maintainable Codebase](maintainable-codebase.md)
-
-## Sub-Principles
-
-- (none)

package/.dust/principles/minimal-dependencies.md

@@ -1,13 +0,0 @@
-# Minimal Dependencies
-
-Dust should avoid coupling to specific tools so we can switch to better alternatives as they emerge.
-
-By keeping dependencies minimal and using standard APIs where possible, we maintain the freedom to adopt new tools without major rewrites. This applies to runtimes, test frameworks, build tools, and other infrastructure choices.
-
-## Parent Principle
-
-- [Maintainable Codebase](maintainable-codebase.md)
-
-## Sub-Principles
-
-- [Runtime Agnostic Tests](runtime-agnostic-tests.md)

package/.dust/principles/naming-matters.md

@@ -1,14 +0,0 @@
-# Naming Matters
-
-Good naming reduces waste by eliminating confusion and making code self-documenting.
-
-Poor names cause rework, bugs, and communication overhead. When names don't clearly convey meaning, developers waste time deciphering code, misunderstand intentions, and introduce defects. Well-chosen names serve as documentation that never goes stale, reducing the need for explanatory comments and enabling both humans and AI agents to navigate the codebase efficiently.
-
-## Parent Principle
-
-- [Maintainable Codebase](maintainable-codebase.md)
-
-## Sub-Principles
-
-- [Consistent Naming](consistent-naming.md)
-- [Clarity Over Brevity](clarity-over-brevity.md)

package/.dust/principles/progressive-disclosure.md

@@ -1,15 +0,0 @@
-# Progressive Disclosure
-
-Dust should reveal details progressively as a way of achieving context window efficiency.
-
-Not all information is needed at once. A task list showing just titles is sufficient for choosing what to work on. Full task details are only needed when actively implementing. Linked principles and facts can be followed when deeper context is required.
-
-This layered approach keeps initial reads lightweight while preserving access to complete information when needed.
-
-## Parent Principle
-
-- [Context Window Efficiency](context-window-efficiency.md)
-
-## Sub-Principles
-
-- (none)

package/.dust/principles/readable-test-data.md

@@ -1,48 +0,0 @@
-# Readable Test Data
-
-Test data setup should use natural structures that mirror what they represent.
-
-## Why it matters
-
-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.
-
-## In practice
-
-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
-
-## How to evaluate
-
-Work supports this principle when test setup data uses structures that visually resemble what they represent, reducing cognitive load for readers.
-
-## Parent Principle
-
-- [Make Changes with Confidence](make-changes-with-confidence.md)
-
-## Sub-Principles
-
-- (none)

package/.dust/principles/reasonably-dry.md

@@ -1,13 +0,0 @@
-# Reasonably DRY
-
-Don't repeat yourself is a good principle, but don't overdo it.
-
-Extracting shared code too eagerly can create tight coupling, obscure intent, and make changes harder. When two pieces of code look similar but serve different purposes or are likely to evolve independently, duplication is the better choice. The cost of a wrong abstraction is higher than the cost of a little repetition. Extract shared code when the duplication is truly about the same concept and has proven stable, not just because two things happen to look alike right now.
-
-## Parent Principle
-
-- [Maintainable Codebase](maintainable-codebase.md)
-
-## Sub-Principles
-
-- (none)

package/.dust/principles/repository-hygiene.md

@@ -1,14 +0,0 @@
-# Repository Hygiene
-
-Dust repositories should maintain a clean, organized state with minimal noise.
-
-This includes proper gitignore configuration to exclude build artifacts, dependencies, editor files, and other generated content from version control. A well-maintained repository makes it easier for both humans and AI to navigate and understand the codebase.
-
-## Parent Principle
-
-- [Maintainable Codebase](maintainable-codebase.md)
-
-## Sub-Principles
-
-- [Atomic Commits](atomic-commits.md)
-- [Trunk-Based Development](trunk-based-development.md)

package/.dust/principles/reproducible-checks.md

@@ -1,13 +0,0 @@
-# Reproducible Checks
-
-Every check must produce the same result regardless of who runs it, when, or on what machine. If a check passes for one developer but fails for another, the check is broken.
-
-Concretely, checks should pin their tool versions via the project's dependency manager (e.g. `devDependencies`) rather than relying on `npx`/`bunx` to fetch the latest version at runtime. Unpinned versions introduce non-determinism — a check that passed yesterday may fail today due to a tool upgrade that nobody chose to adopt.
-
-## Parent Principle
-
-- [Make Changes with Confidence](make-changes-with-confidence.md)
-
-## Sub-Principles
-
-- (none)

package/.dust/principles/runtime-agnostic-tests.md

@@ -1,13 +0,0 @@
-# Runtime Agnostic Tests
-
-Dust's test suite should work across JavaScript runtimes.
-
-Tests should use standard JavaScript testing patterns that work across Node.js, Bun, and other runtimes. Avoiding runtime-specific test APIs ensures the project can leverage different runtimes' advantages while maintaining broad compatibility.
-
-## Parent Principle
-
-- [Minimal Dependencies](minimal-dependencies.md)
-
-## Sub-Principles
-
-- (none)

package/.dust/principles/self-contained-repository.md

@@ -1,17 +0,0 @@
-# Self-Contained Repository
-
-Where possible, developers and agents should have everything they need to be productive, within the repository.
-
-No third-party tools should be required beyond those that can be installed with a single command defined in the repository. Setup instructions, scripts, configuration, and dependencies should all live in version control so that cloning the repo and running a single install command is sufficient to start working. This eliminates onboarding friction, reduces "works on my machine" issues, and is especially important for agents — who cannot browse the web to find missing tools or ask colleagues how to set things up.
-
-## Applicability
-
-Internal
-
-## Parent Principle
-
-- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
-
-## Sub-Principles
-
-- (none)

package/.dust/principles/self-diagnosing-tests.md

@@ -1,54 +0,0 @@
-# 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()
-```
-
-## The test
-
-If a test fails, can a developer who has never seen the code identify the problem from the failure output alone — without re-running, adding console.logs, or reading the test source? The closer to "yes", the better.
-
-## How to evaluate
-
-Work supports this principle when every assertion in a system or integration test would, on failure, reveal the actual state richly enough to guide a fix. Bare boolean checks, length-only assertions, and silent conditional guards are violations.
-
-## Parent Principle
-
-- [Make Changes with Confidence](make-changes-with-confidence.md)
-
-## Sub-Principles
-
-- (none)

package/.dust/principles/slow-feedback-coping.md

@@ -1,15 +0,0 @@
-# Slow Feedback Coping
-
-Some feedback is unavoidably slow — dust should offer coping strategies rather than pretending it can be eliminated.
-
-Integration tests, end-to-end tests, deployment pipelines, and external API calls all take time. Pretending they can be made instant is unrealistic. Instead, dust should help developers and agents cope with slow feedback effectively: by structuring work so that fast checks catch most problems early, by batching slow checks intelligently, by providing clear progress indicators, and by ensuring that when slow feedback does arrive, it is actionable and specific.
-
-Strategies include separating fast and slow test suites, running slow checks asynchronously or in CI, caching expensive operations, and designing workflows that minimise how often slow feedback is needed.
-
-## Parent Principle
-
-- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
-
-## Sub-Principles
-
-- (none)

package/.dust/principles/small-units.md

@@ -1,17 +0,0 @@
-# Small Units
-
-Ideas, principles, facts, and tasks should each be as discrete and fine-grained as possible.
-
-Small, focused documents enable precise relationships between them. A task can link to exactly the principles it serves. A fact can describe one specific aspect of the system. This granularity reduces ambiguity.
-
-Tasks especially benefit from being small. A narrowly scoped task gives agents or humans the best chance of delivering exactly what was intended, in a single atomic commit.
-
-Note: This principle directly supports [Lightweight Planning](lightweight-planning.md), which explicitly mentions that "Tasks are small and completable in single commits."
-
-## Parent Principle
-
-- [Agent Autonomy](agent-autonomy.md)
-
-## Sub-Principles
-
-- (none)

package/.dust/principles/some-big-design-up-front.md

@@ -1,34 +0,0 @@
-# Some Big Design Up Front
-
-AI agents lower the cost of architectural exploration, making heavier upfront investment rational during the idea phase.
-
-Agile's rejection of "big design up front" (BDUF) was largely economic: detailed architecture was expensive to produce and often wrong. AI agents change that equation — they can explore multiple variants, prototype them, and measure trade-offs cheaply. When evaluating alternatives costs less, the expected value of avoiding large structural mistakes increases.
-
-This doesn't mean returning to traditional BDUF. Uncertainty about future requirements still limits what prediction can achieve. The insight is that the optimal amount of upfront work has shifted, not that prediction became reliable.
-
-The model is hybrid: thorough AI-assisted exploration during ideas, followed by straightforward execution during tasks. "Lightweight" refers to task-level planning, not idea-level exploration. Invest heavily in understanding alternatives during the idea phase, then decompose into atomic tasks once the direction is clear.
-
-## Convergence Criteria
-
-Exploration should continue until clear trade-offs are identified and the chosen approach can be articulated against alternatives. This is convergence-based, not time-boxed — simple ideas converge quickly, complex architectural decisions require more exploration.
-
-When exploration feels "done":
-
-- Multiple approaches have been considered
-- Trade-offs between approaches are understood
-- The chosen direction has clear justification
-- Remaining uncertainty is about requirements, not design
-
-If a task requires significant design decisions during execution, it wasn't ready to be a task.
-
-## Documenting Alternatives
-
-Ideas should document the alternatives considered and why they were ruled out. This creates a decision log that helps future agents and humans understand context. Include alternatives in the idea body or Open Questions sections.
-
-## Parent Principle
-
-- [Lightweight Planning](lightweight-planning.md)
-
-## Sub-Principles
-
-- (none)

package/.dust/principles/stop-the-line.md

@@ -1,13 +0,0 @@
-# Stop the Line
-
-Any worker — human or agent — should halt and fix a problem the moment they detect it, rather than letting defects propagate downstream.
-
-Originating from the Toyota production system, "Stop the Line" empowers every participant to pause work immediately upon identifying a defect, failing check, or safety hazard. Problems are cheaper to fix at their source than after they've compounded through later stages. In the context of dust, this means agents and humans alike should treat broken checks, test failures, and lint errors as blockers that demand immediate attention — not warnings to be deferred.
-
-## Parent Principle
-
-- [Make Changes with Confidence](make-changes-with-confidence.md)
-
-## Sub-Principles
-
-- (none)

package/.dust/principles/stubs-over-mocks.md

@@ -1,19 +0,0 @@
-# Stubs Over Mocks
-
-Prefer hand-rolled stubs over mocks, in unit tests. Stubs keep tests focused on observable behavior instead of implementation details.
-
-Mocks tend to encode a script of “expected calls” (what was invoked, in what order, with what arguments). That makes tests brittle: harmless refactors (changing internal decomposition, adding caching, batching calls, reordering operations) can break tests even when the externally visible behavior is unchanged. You end up maintaining tests that police how the code works rather than what it does.
-
-Stubs (and especially in-memory emulators) push tests toward the contract: provide inputs, run the code, assert outputs and side effects. When a test fails, it’s usually because a behavior changed, not because the internal call choreography shifted. That improves signal-to-noise, reduces rewrites during refactors, and makes it easier to evolve the implementation.
-
-For external dependencies (databases, queues, object stores, HTTP services), the default choice should be an in-memory emulator: a drop-in replacement that is faithful enough to the real interface/semantics but runs entirely in-process. It gives most of the benefits of integration testing—realistic state transitions, error modes, concurrency behavior where relevant—without the cost, flakiness, and setup burden of booting real infrastructure. It also keeps the test environment hermetic (no network, no shared state), which improves determinism and makes tests fast.
-
-Still use mocks selectively—mainly to assert something is called (e.g., telemetry emission, "at most once" notifications, payment capture guarded by a feature flag) or when a dependency is impossible to emulate. But for most cases, stubs and in-memory emulators produce tests that are clearer, more resilient to refactoring, and better aligned with the system's actual contracts.
-
-## Parent Principle
-
-- [Decoupled Code](decoupled-code.md)
-
-## Sub-Principles
-
-- (none)

package/.dust/principles/task-first-workflow.md

@@ -1,13 +0,0 @@
-# Task-First Workflow
-
-Work should be captured as a task before implementation begins, creating traceability between intent and outcome.
-
-This discipline ensures that every change has a documented purpose. The commit history shows pairs of "Add task" followed by implementation, making it easy to understand why each change was made. It also prevents scope creep by defining boundaries before work starts.
-
-## Parent Principle
-
-- [Lightweight Planning](lightweight-planning.md)
-
-## Sub-Principles
-
-- (none)

package/.dust/principles/test-isolation.md

@@ -1,19 +0,0 @@
-# Test Isolation
-
-Tests should not interfere with one another. Each test must be independently runnable and produce the same result regardless of execution order or which other tests run alongside it.
-
-This means:
-- No shared mutable state between tests
-- No reliance on test execution order
-- No file system or environment pollution
-- Each test sets up its own dependencies
-
-Test isolation enables parallel execution, makes failures easier to diagnose, and prevents cascading false failures when one test breaks.
-
-## Parent Principle
-
-- [Make Changes with Confidence](make-changes-with-confidence.md)
-
-## Sub-Principles
-
-- [Environment-Independent Tests](environment-independent-tests.md)

package/.dust/principles/traceable-decisions.md

@@ -1,13 +0,0 @@
-# Traceable Decisions
-
-The commit history should explain why changes were made, not just what changed.
-
-Commit messages should capture intent and context that would otherwise be lost. Future maintainers (human or AI) will traverse history to understand the reasoning behind decisions. A commit that says "Fix bug" is less valuable than one that explains what was broken and why the fix is correct.
-
-## Parent Principle
-
-- [Atomic Commits](atomic-commits.md)
-
-## Sub-Principles
-
-- (none)

package/.dust/principles/trunk-based-development.md

@@ -1,19 +0,0 @@
-# Trunk-Based Development
-
-Dust is designed to support a non-branching workflow where developers commit directly to a single main branch.
-
-In trunk-based development, teams collaborate on code in one primary branch rather than maintaining multiple long-lived feature branches. This eliminates merge conflicts, enables continuous integration, and keeps the codebase continuously releasable.
-
-The `dust loop claude` command embodies this philosophy: agents pull from main, implement a task, and push directly back to main. There are no feature branches, no pull requests, no merge queues. Each commit is atomic and complete.
-
-This approach scales through discipline rather than isolation. Feature flags and incremental changes replace long-running branches. The repository history becomes a linear sequence of working states.
-
-See: https://trunkbaseddevelopment.com/
-
-## Parent Principle
-
-- [Repository Hygiene](repository-hygiene.md)
-
-## Sub-Principles
-
-(none)

package/.dust/principles/unit-test-coverage.md

@@ -1,13 +0,0 @@
-# Unit Test Coverage
-
-Complete unit test coverage ensures low-level tests give users direct feedback as they change the code.
-
-Excluding system tests from coverage reporting focuses attention on unit tests - the tests that provide the fastest, most specific feedback. When coverage tools only measure unit tests, developers can quickly identify which parts of the codebase lack fine-grained test protection.
-
-## Parent Principle
-
-- [Make Changes with Confidence](make-changes-with-confidence.md)
-
-## Sub-Principles
-
-- (none)

package/.dust/principles/unsurprising-ux.md

@@ -1,15 +0,0 @@
-# Unsurprising UX
-
-The user interface should be as "guessable" as possible.
-
-Following the [Principle of Least Astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment), users form expectations about how a tool will behave based on conventions, prior experience, and intuition. Dust's interface (including the CLI) should match those expectations wherever possible. If users are observed trying to use the interface in ways we didn't anticipate, the interface should be adjusted to meet their expectations — even if that means supporting many ways of achieving the same result.
-
-Surprising behavior erodes trust and slows people down. Unsurprising behavior lets users stay in flow.
-
-## Parent Principle
-
-- [Easy Adoption](easy-adoption.md)
-
-## Sub-Principles
-
-- (none)

package/.dust/principles/vcs-independence.md

@@ -1,13 +0,0 @@
-# VCS Independence
-
-Dust should work independently of any specific version control system.
-
-While git is common, dust's core functionality should not require git. This enables use in repositories using other VCS (Mercurial, SVN, Perforce) or in non-VCS workflows.
-
-## Parent Principle
-
-- [Easy Adoption](easy-adoption.md)
-
-## Sub-Principles
-
-- (none)