@joshski/dust 0.1.105 → 0.1.107

package/dist/core-principles.js

@@ -1,8 +1,1362 @@
-// lib/core-principles.ts
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { existsSync, readdirSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+// lib/bundled-core-principles.ts
+var BUNDLED_PRINCIPLES = [
+  {
+    slug: "batteries-included",
+    content: `# Batteries Included
+
+Dust should provide everything that is required (within reason) for an agent to be productive in an arbitrary codebase.
+
+An agent working autonomously should not be blocked because a tool or configuration is missing. For example, dust should ship custom lint rules for different linters, even though those linters are not dependencies of dust itself. If an agent needs a capability to do its job well in a typical codebase, dust should provide it out of the box.
+
+This means accepting some breadth of scope — bundling configs, rules, and utilities that target external tools — in exchange for agents that can start producing useful work immediately without manual setup.
+
+## Applicability
+
+Internal
+
+## Parent Principle
+
+- [Agent Autonomy](agent-autonomy.md)
+
+## Sub-Principles
+`
+  },
+  {
+    slug: "some-big-design-up-front",
+    content: `# 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)
+`
+  },
+  {
+    slug: "design-for-testability",
+    content: `# Design for Testability
+
+Design code to be testable first; good structure follows naturally.
+
+Testability should be a primary design driver, not a quality to be retrofitted. When code is designed to be testable from the start, it naturally becomes decoupled, explicit in its dependencies, and clear in its interfaces.
+
+The discipline of testability forces good design: functions become pure, dependencies become explicit, side effects become isolated. Rather than viewing testability as a tax on production code, recognize it as a compass that points toward better architecture.
+
+This is particularly important in agent-driven development. Agents cannot manually verify their changes—they rely entirely on tests. Code that resists testing resists autonomous modification.
+
+## Parent Principle
+
+- [Decoupled Code](decoupled-code.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "readable-test-data",
+    content: `# 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)
+`
+  },
+  {
+    slug: "agent-specific-enhancement",
+    content: `# Agent-Specific Enhancement
+
+Dust should detect and enhance the experience for specific agents while remaining agnostic at its core.
+
+While Dust has [Agent-Agnostic Design](agent-agnostic-design.md) and works with any capable agent, it can still optimize the "agent DX" (developer experience) when it detects a specific agent is being used. This means:
+
+- **Detection** - Dust may detect which agent is running (e.g., Claude Code, Aider, Cursor) through environment variables, configuration, or other signals
+- **Enhancement** - Once detected, Dust can tailor its output format, prompts, or context to leverage that agent's specific strengths
+- **Graceful fallback** - When no specific agent is detected, Dust provides a generic experience that works with any agent
+
+This principle complements Agent-Agnostic Design: the core functionality never requires a specific agent, but the experience improves when one is recognized.
+
+## Applicability
+
+Internal
+
+## Parent Principle
+
+- [Agent Autonomy](agent-autonomy.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "context-optimised-code",
+    content: `# Context-Optimised Code
+
+Code should be structured so that agents can understand and modify it within their context window constraints.
+
+Large files, deeply nested abstractions, and sprawling dependency chains all work against agents. A 3,000-line file cannot be fully loaded into context. A function that requires understanding six levels of indirection demands more context than one that is self-contained. Context-optimised code favours small files, shallow abstractions, explicit dependencies, and co-located related logic.
+
+Dust should help projects identify files that are too large, modules that are too tangled, and patterns that make agent comprehension harder than it needs to be. This is not just about file size — it is about ensuring that the unit of code an agent needs to understand fits comfortably within the window available.
+
+## Parent Principle
+
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "self-diagnosing-tests",
+    content: `# Self-Diagnosing Tests
+
+When a big test fails, it should be self-evident how to diagnose and fix the failure.
+
+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)
+`
+  },
+  {
+    slug: "ideal-agent-developer-experience",
+    content: `# Ideal Agent Developer Experience
+
+The agent is the developer. The human is the CEO. Dust is the PM.
+
+With today's AI coding assistants, the human is stuck in a tight loop with agents — constantly directing, reviewing, and course-correcting. Dust is designed to relieve humans from this tight loop. Like an assistant to a CEO, dust predominantly brings fully-researched questions and well-prepared work to the human, rather than expecting the human to drive every decision. The human checks in less frequently, and when they do, they make high-leverage strategic calls rather than micromanaging implementation.
+
+For this to work, the agent's development environment must be excellent. The agent reads the code, writes changes, runs the checks, and iterates until the task is done. Everything about the codebase and its tooling either helps or hinders that process. Comprehensive tests are the agent's only way to verify correctness. Fast feedback loops are the agent's iteration speed. Structured logs are the agent's eyes into runtime behaviour. Small, well-organised files are what fit in the agent's context window. Exploratory and debugging tools are how the agent navigates and diagnoses without trial and error.
+
+Each sub-principle represents a different aspect of the ideal agent developer setup. The better these are, the less the human needs to be in the loop.
+
+## Parent Principle
+
+- [Human-AI Collaboration](human-ai-collaboration.md)
+
+## Sub-Principles
+
+- [Comprehensive Test Coverage](comprehensive-test-coverage.md)
+- [Fast Feedback Loops](fast-feedback-loops.md)
+- [Slow Feedback Coping](slow-feedback-coping.md)
+- [Development Traceability](development-traceability.md)
+- [Context-Optimised Code](context-optimised-code.md)
+- [Exploratory Tooling](exploratory-tooling.md)
+- [Debugging Tooling](debugging-tooling.md)
+- [Self-Contained Repository](self-contained-repository.md)
+`
+  },
+  {
+    slug: "broken-windows",
+    content: `# Broken Windows
+
+Don't leave broken windows unrepaired.
+
+A broken window — a bad name, a hack, a TODO that lingers, a test that's been skipped — signals that nobody cares. That signal invites more neglect. One shortcut becomes two, then ten, and the codebase quietly rots from the inside.
+
+When you spot a broken window, fix it immediately if the fix is small. If it's too large, capture it as a task so it doesn't get forgotten. The key is to never normalise the damage. Even a comment acknowledging the problem ("this needs fixing because...") is better than silent acceptance.
+
+This principle complements the [Boy Scout Rule](boy-scout-rule.md): the Boy Scout Rule encourages proactive improvement, while Broken Windows warns against tolerating known problems. Together they keep entropy at bay.
+
+## Parent Principle
+
+- [Maintainable Codebase](maintainable-codebase.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "progressive-disclosure",
+    content: `# 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)
+`
+  },
+  {
+    slug: "lightweight-planning",
+    content: `# 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)
+`
+  },
+  {
+    slug: "comprehensive-test-coverage",
+    content: `# Comprehensive Test Coverage
+
+A project's test suite is its primary safety net, and agents depend on it even more than humans do.
+
+Agents cannot manually verify that their changes work. They rely entirely on automated tests to confirm correctness. Gaps in test coverage become gaps in agent capability — areas where changes are risky and feedback is absent. Comprehensive coverage means every meaningful behaviour is tested, so agents can make changes anywhere in the codebase with confidence.
+
+Dust should help projects measure and improve their test coverage, flag untested areas, and encourage a culture where new code comes with new tests.
+
+## Parent Principle
+
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "intuitive-directory-structure",
+    content: `# Intuitive Directory Structure
+
+Code should be organized around related concerns in clearly named directories.
+
+When files that serve similar purposes are grouped together, the codebase becomes easier to navigate and understand. A developer looking for "commands" should find them in a \`commands\` directory. Utilities should live with utilities. This organization reduces cognitive load and makes the project structure self-documenting.
+
+## Parent Principle
+
+- [Maintainable Codebase](maintainable-codebase.md)
+
+## Sub-Principles
+
+- [Co-located Tests](co-located-tests.md)
+`
+  },
+  {
+    slug: "small-units",
+    content: `# 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)
+`
+  },
+  {
+    slug: "fast-feedback",
+    content: `# Fast Feedback
+
+Dust should provide fast feedback loops for developers.
+
+Scripts and tooling should execute quickly so developers can iterate rapidly. Slow feedback discourages frequent validation and leads to larger, riskier changes. Fast feedback enables small, confident steps.
+
+## Parent Principle
+
+- [Make Changes with Confidence](make-changes-with-confidence.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "dependency-injection",
+    content: `# Dependency Injection
+
+Avoid global mocks. Dependency injection is almost always preferable to testing code that depends directly on globals.
+
+When code depends on global state or singletons, testing requires mocking those globals—which introduces hidden coupling, complicates test setup, and risks interference between tests. Dependency injection makes dependencies explicit: they're passed in as arguments, making the code's requirements visible and enabling tests to supply controlled implementations.
+
+This approach improves testability (each test controls its own dependencies), readability (dependencies are declared upfront), and flexibility (swapping implementations doesn't require changing the consuming code). It also makes refactoring safer since dependencies are explicit rather than implicit.
+
+## Parent Principle
+
+- [Decoupled Code](decoupled-code.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "reproducible-checks",
+    content: `# 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)
+`
+  },
+  {
+    slug: "slow-feedback-coping",
+    content: `# 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)
+`
+  },
+  {
+    slug: "make-changes-with-confidence",
+    content: `# 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)
+`
+  },
+  {
+    slug: "test-isolation",
+    content: `# Test Isolation
+
+Tests should not interfere with one another. Each test must be independently runnable and produce the same result regardless of execution order or which other tests run alongside it.
+
+This means:
+- No shared mutable state between tests
+- No reliance on test execution order
+- No file system or environment pollution
+- Each test sets up its own dependencies
+
+Test isolation enables parallel execution, makes failures easier to diagnose, and prevents cascading false failures when one test breaks.
+
+## Parent Principle
+
+- [Make Changes with Confidence](make-changes-with-confidence.md)
+
+## Sub-Principles
+
+- [Environment-Independent Tests](environment-independent-tests.md)
+`
+  },
+  {
+    slug: "repository-hygiene",
+    content: `# 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)
+`
+  },
+  {
+    slug: "agentic-flow-state",
+    content: `# Agentic Flow State
+
+Flow is the mental state where work becomes effortless - where you're fully immersed, losing track of time, operating at peak performance. Psychologist Mihaly Csikszentmihalyi identified three conditions that create flow: clear goals, immediate feedback, and challenge-skill balance.
+
+For AI agents, achieving flow state means staying engaged and productive without interruption. Agents enter flow when they have optimal context, comprehensive guard rails, and minimal friction. Context window optimization ensures agents have exactly what they need without cognitive overload. In-session guard rails prevent agents from straying off course or making mistakes that break their momentum.
+
+Dust's design targets these conditions directly:
+
+- **Clear goals**: Task files and lightweight planning give you a concrete target. You know exactly what you're building next.
+- **Immediate feedback**: Fast feedback loops let you see results quickly. Each change confirms you're on track or shows you what to adjust.
+- **Challenge-skill balance**: Small units of work and agent autonomy keep you in the zone - challenged enough to stay engaged, supported enough to succeed.
+- **Context window efficiency**: Progressive disclosure and artifact summarization ensure agents have the right context without overflow.
+- **Comprehensive guard rails**: Lint rules, type checks, and automated validation catch mistakes before they compound.
+
+Everything dust does serves flow. When agents stay in flow, they produce better work, sustain their momentum, and complete tasks autonomously.
+
+## Parent Principle
+
+- (none)
+
+## Sub-Principles
+
+- [Human-AI Collaboration](human-ai-collaboration.md)
+- [Maintainable Codebase](maintainable-codebase.md)
+`
+  },
+  {
+    slug: "stop-the-line",
+    content: `# Stop the Line
+
+Any worker — human or agent — should halt and fix a problem the moment they detect it, rather than letting defects propagate downstream.
+
+Originating from the Toyota production system, "Stop the Line" empowers every participant to pause work immediately upon identifying a defect, failing check, or safety hazard. Problems are cheaper to fix at their source than after they've compounded through later stages. In the context of dust, this means agents and humans alike should treat broken checks, test failures, and lint errors as blockers that demand immediate attention — not warnings to be deferred.
+
+## Parent Principle
+
+- [Make Changes with Confidence](make-changes-with-confidence.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "agent-context-inference",
+    content: `# Agent Context Inference
+
+Terse human prompts should trigger the correct agent action.
+
+When a human gives a brief instruction like "the button should be green", the agent should be able to infer what to do. The agent shouldn't require the human to specify file paths, component names, or implementation details that can be discovered from the repository.
+
+This reduces friction for humans and makes agent interactions feel more natural. The burden of context discovery shifts to the agent, which can use dust's CLI and repository structure to find what it needs.
+
+## Applicability
+
+Internal
+
+## Parent Principle
+
+- [Agent Autonomy](agent-autonomy.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "naming-matters",
+    content: `# 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)
+`
+  },
+  {
+    slug: "stubs-over-mocks",
+    content: `# 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)
+`
+  },
+  {
+    slug: "functional-core-imperative-shell",
+    content: `# Functional Core, Imperative Shell
+
+Separate code into a pure "functional core" and a thin "imperative shell." The core takes values in and returns values out, with no side effects. The shell handles I/O and wires things together.
+
+Purely functional code makes some things easier to understand: because values don't change, you can call functions and know that only their return value matters—they don't change anything outside themselves.
+
+The functional core contains business logic as pure functions that take values and return values. The imperative shell sits at the boundary, reading input, calling into the core, and performing side effects with the results. This keeps the majority of code easy to test (no mocks or stubs needed for pure functions) and makes the I/O surface area small and explicit.
+
+## Parent Principle
+
+- [Decoupled Code](decoupled-code.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "development-traceability",
+    content: `# Development Traceability
+
+Structured logging and tracing help agents understand system behaviour without resorting to ad-hoc testing cycles.
+
+When something goes wrong, agents often resort to adding temporary log statements, running the code, reading the output, and repeating — a slow and wasteful debugging loop. Good traceability means the system already records what happened and why, through structured logs, trace IDs, and observable state. This lets agents diagnose issues by reading existing output rather than generating new experiments.
+
+Dust should encourage projects to adopt structured logging, promote traceability as a first-class concern, and provide tools that surface relevant trace information when agents need it.
+
+## Applicability
+
+Internal
+
+## Parent Principle
+
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "keep-unit-tests-pure",
+    content: `# Keep Unit Tests Pure
+
+Unit tests (those run very frequently as part of a tight feedback loop) should be pure and side-effect free. A test is **not** a unit test if it:
+
+- Accesses a database
+- Communicates over a network
+- Touches the file system
+- Cannot run concurrently with other tests
+- Requires special environment setup
+
+"Unit tests" here means tests run frequently during development — not system tests, which intentionally exercise the full stack including I/O. Pure unit tests exercise only business logic, not infrastructure.
+
+The value of pure unit tests is that they are fast, deterministic, and isolate business logic from infrastructure concerns. When unit tests pass but integration or system tests fail, developers can immediately narrow the problem to the boundary layer — a diagnostic "binary chop" that accelerates debugging.
+
+## Migration Guidance
+
+Where existing tests are impure (e.g. they spawn processes, write temporary files, or make network calls), prefer converting them to use in-memory alternatives — stubs, fakes, or dependency-injected doubles — rather than leaving them as-is. Opportunistic migration is fine; a big-bang rewrite is not required.
+
+## Parent Principle
+
+- [Make Changes with Confidence](make-changes-with-confidence.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "co-located-tests",
+    content: `# Co-located Tests
+
+Test files should live next to the code they test.
+
+When tests are co-located with their source files, developers can immediately see what's tested and what isn't. Finding the test for a module becomes trivial—it's right there in the same directory. This proximity encourages writing tests as part of the development flow rather than as an afterthought, and makes it natural to update tests when modifying code.
+
+## Parent Principle
+
+- [Intuitive Directory Structure](intuitive-directory-structure.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "human-ai-collaboration",
+    content: `# Human-AI Collaboration
+
+Dust exists to enable effective collaboration between humans and AI agents on complex projects.
+
+The human is the CEO — they set direction, make strategic decisions, and check in when it matters. Dust is the PM — it manages the work, prepares context, and brings fully-researched questions to the human rather than expecting them to drive every detail. Agents are the developers — they read code, write changes, and iterate autonomously.
+
+Today's AI coding tools keep humans in a tight loop with agents. Dust is designed to loosen that loop, so humans spend less time directing and more time deciding.
+
+## Parent Principle
+
+- [Agentic Flow State](agentic-flow-state.md)
+
+## Sub-Principles
+
+- [Agent Autonomy](agent-autonomy.md)
+- [Easy Adoption](easy-adoption.md)
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+- [Lightweight Planning](lightweight-planning.md)
+`
+  },
+  {
+    slug: "vcs-independence",
+    content: `# 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)
+`
+  },
+  {
+    slug: "environment-independent-tests",
+    content: `# Environment-Independent Tests
+
+Tests must produce the same result regardless of where they run. A test that passes locally but fails in CI (or vice versa) is a broken test.
+
+Concretely, tests should never depend on:
+- Ambient environment variables (e.g. \`CLAUDECODE\`, \`CI\`, \`HOME\`)
+- The current working directory or filesystem layout of the host machine
+- Network availability or external services
+- The identity of the user or agent running the tests
+
+When a function's behavior depends on environment variables, the test must explicitly control those variables (via \`stubEnv\`, dependency injection, or passing an \`env\` parameter) rather than relying on whatever happens to be set in the current shell.
+
+## Parent Principle
+
+- [Test Isolation](test-isolation.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "debugging-tooling",
+    content: `# Debugging Tooling
+
+Agents need effective tools for diagnosing and fixing issues without manual intervention.
+
+Traditional debugging relies on breakpoints, stepping through code, and interactive inspection — techniques that work well for humans but poorly for agents. Agents need debugging tools that produce readable, structured output: stack traces with context, diff-friendly error messages, reproducible test cases, and diagnostic commands that can be run non-interactively.
+
+Dust should help projects adopt agent-friendly debugging practices: structured error output, diagnostic scripts, snapshot testing for complex state, and tools that turn vague symptoms into specific, actionable information.
+
+## Applicability
+
+Internal
+
+## Parent Principle
+
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "atomic-commits",
+    content: `# Atomic Commits
+
+Each commit should tell a complete story, bundling implementation changes with their corresponding documentation updates.
+
+When a task is completed, the commit deletes the task file, updates relevant facts to reflect the new reality, and removes any ideas that have been realized. This discipline ensures that any point in the commit history represents a coherent, self-documenting state of the project.
+
+Clean commit history is essential because archaeology depends on it. Future humans and AI agents will traverse history to understand why decisions were made and how the system evolved.
+
+## Parent Principle
+
+- [Repository Hygiene](repository-hygiene.md)
+
+## Sub-Principles
+
+- [Traceable Decisions](traceable-decisions.md)
+`
+  },
+  {
+    slug: "trunk-based-development",
+    content: `# Trunk-Based Development
+
+Dust is designed to support a non-branching workflow where developers commit directly to a single main branch.
+
+In trunk-based development, teams collaborate on code in one primary branch rather than maintaining multiple long-lived feature branches. This eliminates merge conflicts, enables continuous integration, and keeps the codebase continuously releasable.
+
+The \`dust loop claude\` command embodies this philosophy: agents pull from main, implement a task, and push directly back to main. There are no feature branches, no pull requests, no merge queues. Each commit is atomic and complete.
+
+This approach scales through discipline rather than isolation. Feature flags and incremental changes replace long-running branches. The repository history becomes a linear sequence of working states.
+
+See: https://trunkbaseddevelopment.com/
+
+## Parent Principle
+
+- [Repository Hygiene](repository-hygiene.md)
+
+## Sub-Principles
+
+(none)
+`
+  },
+  {
+    slug: "comprehensive-assertions",
+    content: `# Comprehensive Assertions
+
+Assert the whole, not the parts.
+
+When you break a complex object into many small assertions, a failure tells you *one thing that's wrong*. When you assert against the whole expected value, the diff tells you *what actually happened versus what you expected* — the full picture, in one glance.
+
+Small assertions are like yes/no questions to a witness. A whole-object assertion is like asking "tell me what you saw."
+
+## In practice
+
+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.
+
+The same applies to arrays:
+
+\`\`\`javascript
+// Avoid: partial assertions that hide the actual state
+expect(array).toContain('apples')
+expect(array).toContain('oranges')
+
+// Prefer: one assertion that reveals the full picture on failure
+expect(array).toEqual(['apples', 'oranges'])
+\`\`\`
+
+## How to evaluate
+
+Work supports this principle when test failures tell a rich story — showing the complete actual value alongside the complete expected value, so the reader can understand what happened without re-running anything.
+
+## Parent Principle
+
+- [Make Changes with Confidence](make-changes-with-confidence.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "cross-platform-compatibility",
+    content: `# Cross-Platform Compatibility
+
+Dust should work consistently across operating systems: Linux, macOS, and Windows.
+
+This means:
+- Avoiding platform-specific shell commands or syntax
+- Using cross-platform path handling
+- Testing on multiple platforms when possible
+- Documenting any platform-specific limitations
+
+Cross-platform support broadens adoption and ensures teams with mixed environments can collaborate effectively.
+
+## Parent Principle
+
+- [Easy Adoption](easy-adoption.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "exploratory-tooling",
+    content: `# Exploratory Tooling
+
+Agents need tools to efficiently explore and understand unfamiliar codebases.
+
+When an agent encounters a new codebase — or an unfamiliar corner of a familiar one — it needs to quickly build a mental model: what exists, how it fits together, and where to make changes. Without good exploratory tools, agents waste context on trial-and-error searches, reading irrelevant files, and forming incorrect assumptions.
+
+Dust should promote and integrate tools that help agents explore: dependency graphs, module overviews, search utilities tuned for code navigation, and summaries of project structure. The goal is to make the "orientation" phase of any task as short and reliable as possible.
+
+## Applicability
+
+Internal
+
+## Parent Principle
+
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "reasonably-dry",
+    content: `# 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)
+`
+  },
+  {
+    slug: "runtime-agnostic-tests",
+    content: `# 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)
+`
+  },
+  {
+    slug: "task-first-workflow",
+    content: `# 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)
+`
+  },
+  {
+    slug: "agent-autonomy",
+    content: `# Agent Autonomy
+
+Dust exists to enable AI agents to produce work autonomously.
+
+With sufficient planning and small enough units, this works much better in practice.
+
+## Parent Principle
+
+- [Human-AI Collaboration](human-ai-collaboration.md)
+
+## Sub-Principles
+
+- [Actionable Errors](actionable-errors.md)
+- [Batteries Included](batteries-included.md)
+- [Agent-Agnostic Design](agent-agnostic-design.md)
+- [Agent Context Inference](agent-context-inference.md)
+- [Agent-Specific Enhancement](agent-specific-enhancement.md)
+- [Context Window Efficiency](context-window-efficiency.md)
+- [Small Units](small-units.md)
+`
+  },
+  {
+    slug: "clarity-over-brevity",
+    content: `# Clarity Over Brevity
+
+Names should be descriptive and self-documenting, even if longer.
+
+Abbreviated names like \`ctx\`, \`deps\`, \`fs\`, or \`args\` save a few keystrokes but obscure meaning. Full names like \`context\`, \`dependencies\`, \`fileSystem\`, and \`arguments\` make code immediately understandable without requiring readers to decode conventions. This is especially valuable when AI agents or new contributors read the codebase for the first time.
+
+## Parent Principle
+
+- [Naming Matters](naming-matters.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "fast-feedback-loops",
+    content: `# Fast Feedback Loops
+
+The primary feedback loop — write code, run checks, see results — should be as fast as possible.
+
+Fast feedback is the foundation of productive development, for both humans and agents. When tests, linters, and type checks run in seconds rather than minutes, developers iterate more frequently and catch problems earlier. Agents especially benefit because they operate in tight loops of change-and-verify; slow feedback wastes tokens and context window space on waiting rather than working.
+
+Dust should help projects measure the speed of their feedback loops, identify bottlenecks, and keep them fast as the codebase grows. This includes promoting practices like unit tests over integration tests for speed, incremental compilation, and check parallelisation.
+
+## Parent Principle
+
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "make-the-change-easy",
+    content: `# 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)
+`
+  },
+  {
+    slug: "self-contained-repository",
+    content: `# 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)
+`
+  },
+  {
+    slug: "traceable-decisions",
+    content: `# 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)
+`
+  },
+  {
+    slug: "unit-test-coverage",
+    content: `# 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)
+`
+  },
+  {
+    slug: "decoupled-code",
+    content: `# Decoupled Code
+
+Code should be organized into independent units with explicit dependencies.
+
+Decoupled code is easier to test, understand, and modify. Dependencies are passed in rather than hard-coded, enabling units to be tested in isolation and composed flexibly. This reduces the blast radius of changes and makes the system more maintainable.
+
+## Parent Principle
+
+- [Make Changes with Confidence](make-changes-with-confidence.md)
+
+## Sub-Principles
+
+- [Dependency Injection](dependency-injection.md)
+- [Stubs Over Mocks](stubs-over-mocks.md)
+- [Functional Core, Imperative Shell](functional-core-imperative-shell.md)
+- [Design for Testability](design-for-testability.md)
+`
+  },
+  {
+    slug: "lint-everything",
+    content: `# Lint Everything
+
+Prefer static analysis over runtime checks. Every error caught by a linter is an error that never reaches tests, and every error caught by tests is an error that never reaches production.
+
+Lint markdown, lint types, lint formatting. If it can be checked statically, check it. Linters are fast, deterministic, and catch entire categories of bugs before code even runs.
+
+This project lints:
+- TypeScript (type checking and style)
+- Markdown (broken links, required sections)
+- Task files (structure validation)
+- Principle hierarchy (parent/child consistency)
+
+## Parent Principle
+
+- [Make Changes with Confidence](make-changes-with-confidence.md)
+
+## Sub-Principles
+
+(none)
+`
+  },
+  {
+    slug: "maintainable-codebase",
+    content: `# Maintainable Codebase
+
+The dust codebase should be easy to understand, modify, and extend.
+
+This principle governs how we develop and maintain dust itself, separate from the principles that describe what dust offers its users. A well-maintained codebase enables rapid iteration, reduces bugs, and makes contributions easier.
+
+## Parent Principle
+
+- [Agentic Flow State](agentic-flow-state.md)
+
+## Sub-Principles
+
+- [Make Changes with Confidence](make-changes-with-confidence.md)
+- [Minimal Dependencies](minimal-dependencies.md)
+- [Intuitive Directory Structure](intuitive-directory-structure.md)
+- [Repository Hygiene](repository-hygiene.md)
+- [Naming Matters](naming-matters.md)
+- [Reasonably DRY](reasonably-dry.md)
+- [Make the Change Easy](make-the-change-easy.md)
+- [Boy Scout Rule](boy-scout-rule.md)
+- [Broken Windows](broken-windows.md)
+`
+  },
+  {
+    slug: "agent-agnostic-design",
+    content: `# Agent-Agnostic Design
+
+Dust should work with multiple agents without favoring one.
+
+Rather than implementing agents, Dust generates prompts and context that can be passed to any capable agent. This keeps Dust lightweight and allows teams to use whatever agent tooling they prefer.
+
+Dust may have built-in support for invoking popular agents (Claude, Aider, Codex, etc.), but the choice of agent should always be made by the user at runtime - never hard-coded into repository configuration.
+
+Note: Supporting multiple agents directly contributes to [Easy Adoption](easy-adoption.md), since teams can use their preferred agent tools without being locked into a specific platform.
+
+## Applicability
+
+Internal
+
+## Parent Principle
+
+- [Agent Autonomy](agent-autonomy.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "easy-adoption",
+    content: `# Easy Adoption
+
+Dust should be trivially easy to adopt in any repository.
+
+Getting started with Dust should require minimal friction. A developer should be able to bootstrap Dust in their repository with a single command, without needing to install dependencies, configure build tools, or understand the internals.
+
+This lowers the barrier to entry and encourages experimentation.
+
+## Parent Principle
+
+- [Human-AI Collaboration](human-ai-collaboration.md)
+
+## Sub-Principles
+
+- [Cross-Platform Compatibility](cross-platform-compatibility.md)
+- [Unsurprising UX](unsurprising-ux.md)
+- [VCS Independence](vcs-independence.md)
+`
+  },
+  {
+    slug: "actionable-errors",
+    content: `# Actionable Errors
+
+Error messages should tell you what to do next, not just what went wrong.
+
+When something fails, the message should provide:
+- A clear description of the problem
+- Specific guidance on how to fix it
+- Context needed to take the next step
+
+This is especially important for AI agents, who need concrete instructions to recover autonomously. A good error message turns a dead end into a signpost.
+
+## Parent Principle
+
+- [Agent Autonomy](agent-autonomy.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "consistent-naming",
+    content: `# Consistent Naming
+
+Names should follow established conventions within each category to reduce cognitive load.
+
+Principles use Title Case. File names use kebab-case. Commands use lowercase with hyphens. When naming conventions exist, follow them. When they don't, establish one and apply it consistently. Inconsistent naming creates friction for both humans and AI agents trying to predict or recall identifiers.
+
+## Parent Principle
+
+- [Naming Matters](naming-matters.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "minimal-dependencies",
+    content: `# 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)
+`
+  },
+  {
+    slug: "context-window-efficiency",
+    content: `# Context Window Efficiency
+
+Dust should be designed with short attention spans in mind.
+
+AI agents operate within limited context windows. Every token consumed by planning artifacts is a token unavailable for reasoning about code. Dust keeps artifacts concise and scannable so agents can quickly understand what needs to be done without wading through verbose documentation.
+
+This means favoring brevity over completeness, using consistent structures that are fast to parse, and avoiding redundant information across files.
+
+## Parent Principle
+
+- [Agent Autonomy](agent-autonomy.md)
+
+## Sub-Principles
+
+- [Progressive Disclosure](progressive-disclosure.md)
+`
+  },
+  {
+    slug: "boy-scout-rule",
+    content: `# Boy Scout Rule
+
+Always leave the code better than you found it.
+
+When working in any area of the codebase, take the opportunity to make small improvements — clearer names, removed dead code, better structure — even if they're not directly related to the task at hand. These incremental improvements compound over time, preventing gradual decay and keeping the codebase healthy without requiring dedicated cleanup efforts.
+
+The Boy Scout Rule is not a license for large-scale refactoring during unrelated work. Improvements should be small, obvious, and low-risk. If a cleanup is too large to include alongside the current task, capture it as a separate task instead.
+
+## Parent Principle
+
+- [Maintainable Codebase](maintainable-codebase.md)
+
+## Sub-Principles
+
+- (none)
+`
+  },
+  {
+    slug: "unsurprising-ux",
+    content: `# 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)
+`
+  }
+];
 
 // lib/markdown/markdown-utilities.ts
 function extractTitle(content) {
@@ -11,57 +1365,6 @@ function extractTitle(content) {
 }
 var MARKDOWN_LINK_PATTERN = /\[([^\]]+)\]\(([^)]+)\)/;
 
-// lib/artifacts/principles.ts
-function extractLinksFromSection(content, sectionHeading) {
-  const lines = content.split(`
-`);
-  const links = [];
-  let inSection = false;
-  for (const line of lines) {
-    if (line.startsWith("## ")) {
-      inSection = line.trimEnd() === `## ${sectionHeading}`;
-      continue;
-    }
-    if (!inSection)
-      continue;
-    if (line.startsWith("# "))
-      break;
-    const linkMatch = line.match(MARKDOWN_LINK_PATTERN);
-    if (linkMatch) {
-      const target = linkMatch[2];
-      const slugMatch = target.match(/([^/]+)\.md$/);
-      if (slugMatch) {
-        links.push(slugMatch[1]);
-      }
-    }
-  }
-  return links;
-}
-function extractSingleLinkFromSection(content, sectionHeading) {
-  const links = extractLinksFromSection(content, sectionHeading);
-  return links.length === 1 ? links[0] : null;
-}
-async function parsePrinciple(fileSystem, dustPath, slug) {
-  const principlePath = `${dustPath}/principles/${slug}.md`;
-  if (!fileSystem.exists(principlePath)) {
-    throw new Error(`Principle not found: "${slug}" (expected file at ${principlePath})`);
-  }
-  const content = await fileSystem.readFile(principlePath);
-  const title = extractTitle(content);
-  if (!title) {
-    throw new Error(`Principle file has no title: ${principlePath}`);
-  }
-  const parentPrinciple = extractSingleLinkFromSection(content, "Parent Principle");
-  const subPrinciples = extractLinksFromSection(content, "Sub-Principles");
-  return {
-    slug,
-    title,
-    content,
-    parentPrinciple,
-    subPrinciples
-  };
-}
-
 // lib/artifacts/core-principles.ts
 function sortNodes(nodes) {
   nodes.sort((a, b) => a.title.localeCompare(b.title));
@@ -119,36 +1422,52 @@ function getCorePrincipleTree(allPrinciples, config) {
 }
 
 // lib/core-principles.ts
-function createFileReader() {
-  return {
-    exists: existsSync,
-    readFile: (path) => readFile(path, "utf-8")
-  };
+function extractLinksFromSection(content, sectionHeading) {
+  const lines = content.split(`
+`);
+  const links = [];
+  let inSection = false;
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      inSection = line.trimEnd() === `## ${sectionHeading}`;
+      continue;
+    }
+    if (!inSection)
+      continue;
+    if (line.startsWith("# "))
+      break;
+    const linkMatch = line.match(MARKDOWN_LINK_PATTERN);
+    if (linkMatch) {
+      const target = linkMatch[2];
+      const slugMatch = target.match(/([^/]+)\.md$/);
+      if (slugMatch) {
+        links.push(slugMatch[1]);
+      }
+    }
+  }
+  return links;
+}
+function extractSingleLinkFromSection(content, sectionHeading) {
+  const links = extractLinksFromSection(content, sectionHeading);
+  return links.length === 1 ? links[0] : null;
 }
-function locatePackagePrinciplesDir() {
-  const thisFile = fileURLToPath(import.meta.url);
-  const thisDir = dirname(thisFile);
-  const packageRoot = dirname(thisDir);
-  const principlesDir = join(packageRoot, ".dust", "principles");
-  if (!existsSync(principlesDir)) {
-    throw new Error(`Core principles directory not found at ${principlesDir}. ` + "Ensure the @joshski/dust package is properly installed.");
+function parsePrincipleContent(slug, content) {
+  const title = extractTitle(content);
+  if (!title) {
+    throw new Error(`Principle has no title: ${slug}`);
   }
-  return principlesDir;
+  const parentPrinciple = extractSingleLinkFromSection(content, "Parent Principle");
+  const subPrinciples = extractLinksFromSection(content, "Sub-Principles");
+  return {
+    slug,
+    title,
+    content,
+    parentPrinciple,
+    subPrinciples
+  };
 }
 async function readAllCorePrinciples() {
-  const principlesDir = locatePackagePrinciplesDir();
-  const packageRoot = dirname(dirname(principlesDir));
-  const dustPath = join(packageRoot, ".dust");
-  const fileSystem = createFileReader();
-  const files = readdirSync(principlesDir);
-  const mdFiles = files.filter((f) => f.endsWith(".md"));
-  const principles = [];
-  for (const file of mdFiles) {
-    const slug = file.replace(/\.md$/, "");
-    const principle = await parsePrinciple(fileSystem, dustPath, slug);
-    principles.push(principle);
-  }
-  return principles;
+  return BUNDLED_PRINCIPLES.map(({ slug, content }) => parsePrincipleContent(slug, content));
 }
 async function getCorePrincipleSlugs(config = {}) {
   const allPrinciples = await readAllCorePrinciples();
@@ -158,15 +1477,10 @@ async function getCorePrincipleHierarchy(config = {}) {
   const allPrinciples = await readAllCorePrinciples();
   return getCorePrincipleTree(allPrinciples, config);
 }
-function getCorePrinciplesPath() {
-  const principlesDir = locatePackagePrinciplesDir();
-  return `${principlesDir}/`;
-}
 export {
   readAllCorePrinciples,
   listCorePrinciples,
   isInternalPrinciple,
-  getCorePrinciplesPath,
   getCorePrincipleTree,
   getCorePrincipleSlugs,
   getCorePrincipleHierarchy