git:20261103.ed983ac to git:20261106.c8d7a7f

- This is the governing document of the loopflow codebase. Contributors and agents alike are expected to follow it.

- **Wave planning:**

- - Authored Wave goals, memory, and metrics live under `.lf/wave/<name>/`; top-level `wave/` is ordinary repository content.

- - Wave = durable objective, responsibility, memory, cadence, budget, chat, and metric instruments

- - Chapter = shared name of every Wave's In Progress Linear Project; no Chapter table

- - Project = one Wave's Linear plan: status, Tasks, KRs and targets

- - A Task's work is every Session, Graph and Process in its checkout, plus explicit binds; no Graph is selected over another

- - A Task's workflow is the graph it took up and the step it stands at; workflows are ordinary graph files, never a second definition kind. An `interactive:` step is where a person takes part: `lf graph` runs it in place, `lf task run` stops before it (the Task waits in its conversation) and the next run continues after it; `--from <step>` starts anywhere; `-i`/`-b` choose for every step of a launch

- - Task completion, graph position and Process liveness are independent; reaching `end` requests completion, and a failed request retries without replaying the run

- - Task state = `unstarted · idle · active · moving · shipping · done · abandoned`, derived from checkout, graph position, a running Graph and the Auto-Ship approval; Session state (`available · busy`) is a separate axis. Working Tasks are idle, active or moving. Ownership is separate: `lf task claim` assigns, `lf task unassign` clears the owner and Linear assignee, and nothing (ship, CI repair, Wave operators) moves an unassigned Task. `lf ship` or any run into `end` approves Auto-Ship, which may land the PR; `lf ship --stop` withdraws it until the next `lf ship`, and a stopped Task's run waits at its landing step. `lf task run` launches; `-b` approves like `lf ship`

- - Started unfinished Tasks move with identity, worktree, PR, and invocation intact

- - Unreviewed backlog stays in its Project until explicit disposition; uncertain evidence never auto-closes work

- - Current navigation is Wave → Task; chapter history retains each Wave's past plan

- - Definitions name the beneficiary and experienced improvement; KRs prove it

-

- - Return `None` for "not found"; raise exceptions for "shouldn't happen"

- - No `Args:`/`Returns:` docstrings—if types are clear, skip the docstring

- - Run `cargo fmt` and `cargo clippy` before committing

- - Return `Option<T>` for "not found"; return `Result<T, E>` for failures

- - Use `expect("reason")` over `unwrap()` outside tests

- - Mock side effects, but don't test mock wiring or reshape production code for tests

- - Design docs go under `scratch/`; `lf pr submit` and `lf pr land` invoke `lf scratch clear`, removing added files while retaining existing files and edits

- - Auto runs are headless: make executive decisions and keep moving, note genuinely ambiguous choices in `scratch/questions.md`

- - Fetch every secret from Doppler — never hardcode a key, read it from a dotfile, or paste one into code. Prefer `doppler run -- <cmd>` (injects the value as an env var; it never surfaces).

- - A raw value must never reach a terminal, log, or chat. `doppler secrets get NAME --plain` **prints the value** — so never run it bare: consume it inline in a command substitution (`curl -H "Authorization: Bearer $(doppler secrets get NAME --plain)"`) or redirect it (`> file`, or a clipboard pipe like `| pbcopy` on macOS / `| xclip` on Linux) — never to stdout.

- - Inspect with `doppler secrets --only-names`. Redirect writes: `doppler secrets set NAME > /dev/null` (the bare `set` echoes the whole config **with values**). Never `echo` a key.

- - If a value does leak into output, say so and flag it for rotation — don't quote it again.

- Use people's names in persisted artifacts: Tasks, PRs, designs, memory,

- reports, and decision summaries. Write “Jack requested the prototype path.”

- In session conversation, use “you”: “You requested the prototype path.”

- Storing a transcript does not change its wording; a summary written from it

- uses names. Refer to other participants by name. Use known preferred names,

- never infer authorship from a machine owner or account. Ask when a necessary

- name is missing, or record that attribution is unresolved.

-

- Describe agents as available for people to do their work with. Name the work,

- the available interaction, and actual constraints. Never portray people as

- blockers or as owing agents attention. Availability is independent of a pending

- question, review or Task dependency. Preserve real authorization and failures.

- Write in language the user would use themselves. Never refer to a person as

- “the human.” Generic role labels belong in instructions where the role matters,

- not in place of known names in authored artifacts.

- The creator's flow is sacred. Every interaction either sustains it or breaks it.

- Name conversations for the requested work in two or three words, with the Task

- identifier first when known. Never use the title of these instructions, an

- operating guide or an operator role as the conversation name. This applies to

- fresh and resumed conversations, including direct native agent invocation.

- first if prior work needs preserving (see this file's "Checkpoint and

- proceed" section). "Do you want me to get started on..." breaks flow when the

- answer is obviously yes.

- - "Do you want me to get started on..." / "Should I begin..." / "Ready for me to..." - for reversible work, checkpoint and proceed

-

- ## File-Type Guidelines

-

- When editing `*.py` files:

- - Put imports at the top, not inline

- - Use type hints on all public functions

- - One-line docstring if any; skip if the name and types are clear

-

- When editing `*_test.py` or `test_*.py` files:

- - Keep tests short and focused on one behavior

- - Mock side effects (network, subprocess), but assert on results, not mock calls

- - Delete flaky tests rather than adding retries

-

- When writing CLI code with Typer:

- - Prefer lowercase short flags (`-p`, `-c`), do not add uppercase aliases

- - Pass args through to underlying tools rather than re-implementing

- - Default to sensible behavior (e.g., whole repo as context)

-

- When editing builtin skills (`builtins/**`):

- - Skills must be self-contained: never reference repo-relative docs or files —

- the skill runs in repos that don't have them. Inline the compressed guidance;

- the long form lives in this repo's docs for readers.

- - Doctrine rides only where it's exercised: teach a rule in the skill that uses

- it, not in every context (LOOPFLOW.md is paid for on every run, everywhere).

-

- When editing `README.md` files:

- - Examples first, explanation after—show `lf debug -c`, then say what it does

- - Action-focused tables: "What it does" not "What it is"

- - Terse prose around code blocks—the code speaks

- - One good example beats three similar ones

- - No preamble: "Assembles context" not "Loopflow assembles context for you"

- - Write for users, not maintainers

- - Update when adding or changing user-facing features

-

- When editing docs in `scratch/`:

- - Focus on what's left to build, not what's done

- - `lf realign` updates the existing plan, code, and relevant memory; keep unresolved findings with the work

- - `lf pr submit` and `lf pr land` invoke `lf scratch clear`, removing added files while retaining existing files and edits

-

- When changing the SQLite schema:

- - Keep one migration per Task: `uv run python scripts/new_migration.py <name>` creates `migrations/<name>.sql` or prints the one the branch already has

- - Edit it in place until it merges; `build.rs` orders it by origin/main's first-parent history. Once on origin/main it is immutable: fix it forward

- - Test the merged frontier against the finished migration, not the steps between

- - Tables read by Work projections use `store_revision_<table>_<insert|update|delete>`

- triggers to advance their domain in `store_revisions` inside the write.

- - Runtime migration preflights recognize draft markers inside release batches and

- retain external lock guards through commit or rollback. Upgrade fixtures start

- before the whole release batch, not before a draft within it.

- - Seed a released schema from SQL under `rust/loopflow/tests/fixtures/migrations/`; test sources name only current columns

-

- When editing `*.rs` files:

- - Run `cargo fmt` before committing; CI enforces it

- - Run `cargo clippy --all-targets -- -D warnings` locally; CI treats warnings as errors

- - Dead code must be deleted, not commented out (use git for history)

- - If code is intentionally unused (e.g., for FFI/PyO3), use `#[allow(dead_code)]` with a comment explaining why

- - Avoid `use super::*` in submodules; use explicit imports so dependencies between modules are visible

- - Derive `Debug` on all public types; add `Clone`, `PartialEq`, `Default` where sensible

- - Canonicalize Clap command aliases in shared navigation so help, remote routing and execution resolve the same owner.

- - `lf help <path>` renders Clap's short help; text it must show (exit statuses, caveats) goes in `after_help`, not a second doc-comment paragraph.

- - Give nested global Clap flags a distinct argument `id` when a root flag shares their name; otherwise their values can propagate into the root command.

- - Use `thiserror` for library error types callers need to match on

- - Long-lived deadlines (a Session's grace, a limit measured in minutes or hours) use

- `SystemTime`: `Instant` stops while a Mac sleeps, so an `Instant` limit of 24h can

- take days of wall time. `Instant` stays for short pauses and throttles.

- - Use `expect("why this is safe")` over `unwrap()` outside tests

- - Conversion methods: `as_` (cheap/borrowed), `to_` (allocates), `into_` (consumes self)

- - No `get_` prefix on getters: `fn name(&self)` not `fn get_name(&self)`

- - Return `Option<T>` for "not found", `Result<T, E>` for "something went wrong"

- - Newtypes for domain concepts: `struct LfProcessId(String)` not `type LfProcessId = String`

- - Every `unsafe` block requires a `// SAFETY:` comment explaining invariants

- - When a name conflicts with a keyword: use `r#type` or `type_`, not `typ`

- - Use `#[non_exhaustive]` on public enums that may grow

- - Never use `()` as an error type

- - SQLite read helpers that join statements use savepoints so they compose inside

- the Work reader's pinned snapshot as well as standalone. Keep write transactions

- at their existing command boundaries.

- - For public APIs, include `# Panics`/`# Errors`/`# Safety` doc sections where non-obvious

-

- When editing Rust tests:

- - `unwrap()` is fine in tests

- - Use `#[test]` for unit tests in the same file

- - Integration tests go in `tests/` directory

- - Bare `task run` returns once the Graph registers; `lf -b task run` waits, but also runs interactive steps headless. A test that reads state a stopping run writes waits for that run to finish. `lf ship` and `-b` share one path. A change to when a command returns inventories its test callers too (`grep -rn '"task", "run"' rust/loopflow/tests/`).

- - Register standalone test binaries in `rust/loopflow/Cargo.toml` (`autotests = false`); ordinary suites join `tests/integration.rs`.

- - Mock via closures or `#[cfg(test)]`, not factory traits or extra abstractions

- - Pin fixture `LF_BIN` inside the network boundary; the runner clears inherited `LF_*`. Never let an installed provider outrank a stand-in.

- - From an lf-launched shell, run `cargo test` with inherited `LF_*` unset and `< /dev/null`: capture fixtures follow `LF_HOME`, and `lf task create` reads a piped report from open stdin. In zsh that is `env $(env | grep '^LF_' | cut -d= -f1 | sed 's/^/-u /') cargo test …`; an unquoted `$VAR` does not word-split, and a leftover `LF_CAPTURE_KEY` fails store writes with CannotOpen or "capture does not belong to a recorded Session".

- - Claims name their person by the Task repository's Git `user.email` and fail without one; fixtures set a repository-local identity (`TestRepo` does), and CI test jobs set only a global fallback.

- - Library and integration fixtures that mutate process environment share `loopflow_test_support::env_lock`; per-suite locks cannot isolate library modules.

- - `SqliteStore::open_ephemeral` applies the build's whole migration catalog; do not

- replay a migration with `apply_migration_for_test`.

- - Fake `gh` scripts route `api graphql` calls by query name; renaming a query means grepping `rust/loopflow/tests/` (standalone binaries included) for the old name.

- - Tests that redirect process-wide stdout/stderr descriptors run in isolated child processes, never in the shared test runner.

- - Native library fixtures use `TestLedgerGuard` so invocation and capture share a store. Pin blocking workers with `journal::with_test_ledger`; thread-local fixture selection does not follow `LF_HOME`.

- Design around data structures and public APIs. Aim for a 1:1 mapping between real-world concepts and their representation in code.

- Write code that demonstrates its own correctness. If a feature exists, write a test that proves it works. Assume you won't finish everything you start—make it easy to see what's done and what's broken.

- Every line of code must earn its place. Readable code is not terse code; don't sacrifice clarity for brevity. But recognize that lines can be net-negative:

-

- * Unused code

- * Comments that restate the obvious

- * Checks for impossible conditions

- Start with minimal data structures and APIs. If the core is right, trimming excess at the edges is straightforward.

- A redesign deletes what it replaces. We have usually tried the idea before, and half-built versions remain: an unreachable branch, a hidden command, a second resolver. Find them before designing. If three building blocks exist for one job and none quite works, the change removes all three in the same diff. It does not add a fourth.

- Meet the caller where they are. When code breaks because it assumed a fixed context—running on `main`, an un-owned worktree, an ambient home—accept the context and adapt to it. Resolve the right thing automatically; don't add a guard, a verification, an allowlist, or a precondition that refuses.

-

- Rigidity is usually what caused the failure: refuse the context, and someone works around the refusal and corrupts state. Flexibility deletes the whole failure class. Every guard is one more thing to remember and one more thing that can drift across hand-mirrored layers.

-

- The instinct on a bug is often a new check. Invert it: can the system adapt instead? Prefer dropping a precondition to adding one. If a fix reads as "extend the allowlist," "verify identity," or "add scaffolding," reframe it as a reduction before shipping. The best fix makes the system smaller and gets in our own way less.

-

- ## Wave Planning

-

- A Wave's objective, memory, cadence, budget and instruments survive planning

- boundaries. A Chapter is the shared name of each Wave's one In Progress Linear

- Project. Linear Project status owns current/planned/completed history; there is

- no Chapter table or plan packet. Project owns Tasks, KRs and targets. Wave owns the optional default graph; repository `graph:`, then builtin `code`, are the defaults after it.

- A Task's work includes every Session, Graph and Process associated with

- its checkout, plus explicit binds. Rust owns this shared association for status,

- Desktop navigation, recovery and completion. Membership grants no process or

- Graph authority and never rewrites historical usage. Every Graph naming the Task

- is equally its work; a stopped Graph is history its caller inspects, never a

- position to resume. A Task with no graph takes up its Wave's default, then repository `graph:`,

- then `code`, on its first `lf task run`; one that named its own keeps it. Its graph and

- position are one `task_graphs` row that only `lf task run` (and `lf ship`, which is

- `-b task run` repeated) moves; other Graphs in the checkout never do. `lf graph` handles

- definitions and `--processes` inspects execution. Task projections expose the Task's

- graph, latest GraphProcessDetail, execution evidence and TaskRunControl separately;

- latest never grants primary authority. The graph is fixed when taken up. `lf task run`

- starts the run as a child Graph process, again when one fails, and that Graph writes

- where it left the Task: before the interactive step it stopped at, or at `end`. A run

- that stops leaves the Task on it, and the next `lf task run` starts that run again from

- where it began. `lf task move --wave/--no-wave` changes membership without transferring

- execution. No command approves or completes a step.

- Taskless execution uses the same Graph runner. A Graph is one lf process and the step

- Processes it starts; its id is the Graph process ID. The Graph process holds the cursor and

- return counts in memory and writes GraphProcess, append-only: the Graph's name and

- compiled graph at launch, then each step's Process, node and iteration counts.

- Every Graph process gets one; none is primary for a Task. A step is the plain command

- (`lf -b skill <name> [message]` or the operation's own) and neither reads nor

- writes it. Running, finished and results are read from Processes, never stored

- twice. GraphComposition describes resolved composition, which expands the graph; loop passes are node/iteration

- positions on step rows, not child Graphs.

- Repository rotation converges on an explicit target through fresh provider facts

- and stable Project identities. Partial status changes remain retryable; unrelated

- competing plans remain unresolved. Preserve active Task identity, worktree, PR

- and execution. Preserve unreviewed backlog until explicit disposition; missing evidence is unknown.

- Current navigation stays Wave → Task and Linear retains past Projects.

- LfProcess is one actual lf process that changes Work, including direct and agent-issued

- nested commands; reads, navigation and arrangement record none (`Commands::changes_work`).

- Its `id`, an `LfProcessId`, is durable Loopflow identity; `pid` is only the optional

- Unix PID and may collide across history. References are `<role>_lf_process_id`:

- `lf_process_id`, `parent_lf_process_id`. AgentProcess is the provider's OS process

- Loopflow started: one `processes` row of kind `agent`, with its parent LfProcess,

- the attached LfProcess and a fresh attachment token. It survives attachment handoff.

- LfSession is one Loopflow-owned durable conversation, interactive or headless; identity,

- name, feedback and native history survive takeover. Product text says

- Session for interactive and Run for headless work. AgentSession is the provider-owned

- conversation, represented by an opaque AgentSessionId used for resume, native

- turn keys and account attribution. An LfSession selects one AgentSession at a

- time; replacement preserves earlier selections in immutable history. It is not

- an OS process and has no separate table. Available is the one attention

- state, judged in Rust from owned provider streams and validated terminal reports. A step's result

- is how its process exited; a deciding or routing step also answers through the

- Session turn its Process captured. Agent outcomes and retries belong in Session

- history; mechanical results are step Process exits. A Session reaches its Graph

- through the step Process that captured its input. Do not replace Run with another

- generic attempt object.

- Main records have one SQLite owner. Every Task has a repository and optional Project membership; its Wave is derived through that Project. Constructors reject mismatched ancestry. Bind assigns an unassigned conversation once,

- including to done/landed Tasks. Prospective attribution preserves earlier usage owners; the history reader

- owns that single choice. Actual work

- reservation claims an unowned Task in the ownership log; logging an inspection Process does not. Every

- denormalization is removed or validated on writes. Causal ancestry grants neither

- process control nor Graph settlement. Attachment claims and provider identity

- are separate: a fresh claim token fences every attachment and release, including

- A → B → A, while an unchanged provider survives handoff. Passive display acquires no claim.

- The full contract lives in

- [Core models and APIs](docs/architecture/reference-models.md#core-models-and-apis);

- the [Architecture Reference](docs/architecture-reference.md) indexes the rest,

- including cutover status.

- Use `uv` for Python package management. Never use pip directly.

- cargo fmt # format

- cargo clippy --all-targets -- -D warnings # lint after tests (warnings = errors)

- uv sync # install Python dependencies

- `build.rs` downloads the pinned `libghostty-vt` archive for the build target once

- per target directory (`rust/loopflow/ghostty-vt.json`, `rust/loopflow/ghostty-vt-patches/README.md`);

- offline, point `LOOPFLOW_GHOSTTY_VT_DIR` at a directory holding `libghostty-vt.a`.

- Run one cargo command at a time: concurrent builds wait on one target lock.

- CI runs the full matrix; locally, run it only to reproduce a CI failure.

- When accepted work needs a developer tool the Machine lacks, install it

- (Homebrew on macOS) and configure it at Machine level, then continue; a

- missing tool is never a reason to defer. Keep Machine-only tools out of

- repository config CI also reads: sccache runs through `~/.cargo/config.toml`.

- `scripts/testing.md` holds the shared command list, and module READMEs

- (`rust/loopflow/tests/`, `scripts/`, `swift/`, `website/`) and `.github/CI.md` own

- their boundary checks.

- Follow PEP8. Consistency with existing code matters more than any specific rule.

-

- Keep `__init__.py` files empty. They exist only to mark directories as packages. Don't use them for re-exports—import from the actual module (`from loopflow.models import WaveSnapshot`) rather than a package-level re-export. A docstring describing the package contents is fine.

-

- Keep information in one place. Version numbers, configuration, documentation—each piece of information should have a single source of truth. Don't duplicate versions in `__init__.py` and `pyproject.toml`. Don't copy FAQs into multiple READMEs. If something needs to appear in multiple places, generate it or reference the source.

-

- Put imports at the top of the file. Declare dependencies in `pyproject.toml` and assume they're available.

-

- Prefer explicit imports over magic. Don't inject names into module namespaces to save one import line—it breaks linters, IDE autocomplete, and confuses readers. If a module needs `Graph`, it should `from loopflow.lf.graphs import Graph`. Standard Python beats clever patterns that fight tooling.

-

- Keep one implementation. Avoid `v2_`, `_old`, `_new`, `_backup` prefixes and suffixes—look up old versions in git. If you're tempted to keep both old and new code around, delete the old version and commit. You can always get it back from git if needed.

-

- Don't maintain backwards compatibility unless explicitly required. If a config format or API changes, migrate everything to the new format—don't write code that handles both old and new. Backwards compatibility is for production databases and published APIs with external users, not internal config files. Unless the design doc specifies a migration path, assume we don't want compatibility shims.

-

- One exception: a file that the released lf and a branch build both read, such as `.lf/config.yaml`. Until the new shape is released and installed, the branch keeps the released shape readable, so the change doesn't break the released build in its own repository. Mark the fallback with the Task that removes it, and file that Task in the same change.

- Use header comments to group related code sections.

- ## Naming

- Use verb-first names for action functions: `find_prompt()`, `load_config()`, `create_worktree()`.

- Prefix private functions with underscore: `_should_ignore()`, `_load_file()`.

- Name things after what they are, not what they're for: `Document`, `FileEdit`, `Target`—not `DocumentHelper`, `EditResult`, `OutputHandler`.

- ## Type Hints

- Use `Optional[X]` only when a value is truly optional (caller can omit it):

- # Good: caller can omit repo_root

- def find_prompt(name: str, repo_root: Optional[Path] = None) -> Path: ...

-

- # Bad: None means "not found"—that's an error, not an option

- def get_user() -> Optional[User]: ...

- ## Error Handling

-

- Errors are for users; exceptions are for programmers.

- Return errors when the caller should handle them—invalid input, missing files, failed requests. Raise exceptions for bugs: violated invariants, impossible states, programming mistakes.

- ```python

- # Error: caller decides what to do

- def find_config(path: Path) -> Optional[Config]:

- if not path.exists():

- return None

- return load(path)

- # Exception: this shouldn't happen

- def get_target(name: str) -> Target:

- if name not in TARGETS:

- raise ValueError(f"Unknown target: {name}")

- return TARGETS[name]

- ```

- When in doubt: if you'd write an `assert`, raise an exception instead—it's easier for callers to catch.

- ## DTOs

- Wire types — anything emitted by `lf --json` and mirrored in Rust and Swift — get no defaults. Every field is either required or explicitly Optional.

- - No `#[serde(default)]`, no `Default` derive, no `#[serde(default = "...")]` on DTOs.

- - No Swift init default parameters on DTO structs. No `?? value` fallbacks in JSON parsing — if the field can be absent, its type is `T?`.

- - No Rust `Option<T>` with `#[serde(default)]` masquerading as "empty is fine"; decide required-or-Optional and surface it in the type.

- Why: hand-maintained mirrors drift when defaults live at different layers. A field that quietly defaults to `true` in one language and `false` in another produces a silent split-brain. The rule kills the drift at the source — if every absent field is either a parse error or an explicit `nil`, the models stay in lockstep without ceremony.

- Round-trip fixture tests under `tests/fixtures/dto/` cover the wire shape. Adding a DTO field means adding it to the fixture and to each language's fixture test.

- UI state types that *carry* DTO values (e.g. Swift `SessionState`) aren't DTOs. Defaults there are a UX choice, not a drift bug.

- # Documentation

- The best documentation is simple code. Descriptive names, type hints, and clear APIs often suffice.

- The worst documentation is wrong documentation. If it can drift from the code, it will. Update docs when you change code—or delete them.

- Put documentation next to code. A few paragraphs at the top of a key file beats a separate doc that nobody maintains.

- Skip obvious docstrings:

- # Bad

- """

- Open Warp terminal at the given path.

-

- Args:

- path: The path to open Warp at

-

- Returns:

- None

- """

- subprocess.run(["open", f"warp://action/new_window?path={path}"])

-

- # Good

- def open_warp(path: Path) -> None:

- subprocess.run(["open", f"warp://action/new_window?path={path}"])

- Give each module a `README.md` for users. Use inline comments for maintainers. Don't duplicate what's in the code.

-

- Start features with a design doc under `scratch/`. After implementation, `lf realign` updates the existing plan, code, and relevant memory. `lf pr submit` and `lf pr land` invoke `lf scratch clear`, removing added files while retaining existing files and edits. The code and its README should speak for themselves.

-

- ## User-Facing Documentation

-

- Guides, examples, skills and agent instructions use the shortest uniquely

- resolving command, such as `lf land`, `lf wt create` or `lf pr publish`.

- Keep canonical owner paths in command references and help, where the tree is

- the point. Preserve established short names; do not expand `wt` to `worktree`.

- `documented_commands` checks example ambiguity against Clap; adding a competing

- command requires updating any shorthand that stops resolving uniquely.

- `docs/lf-reference.md` commits only its authored preamble; `website/dev.py sync-docs`

- appends the command tree from `lf help --all --json` (`LF_BIN` or `lf` on PATH).

- Help text lives in Clap, so a CLI change edits no reference file.

-

- User docs follow the same principles as prompts (see PROMPTS.md):

-

- **Direct and imperative.** State what something does, not what it is. "Runs a prompt with assembled context" beats "A skill is a markdown file containing instructions."

-

- **Examples carry the weight.** Code blocks are the primary content. Prose exists to connect them. If you can cut a paragraph and the examples still make sense, cut it.

- **Tables for reference, not education.** Tables work for quick lookup once you understand the concepts. Lead with examples that teach.

- **No throat-clearing.** Cut "In order to...", "You can use...", "This allows you to...". Just show it.

- This allows you to paste an error and have the agent fix it.

- Test user behavior, not implementation details. A good test proves that something users care about actually works. Most tests don't meet that bar. Delete them.

-

- Aim for a mix:

- - **Smoke tests**: Does the system run without crashing?

- - **Edge case tests**: What happens at boundaries?

- - **Value tests**: Does this feature do what users expect?

-

- ## Verification Cadence

-

- - **Implement/compress:** build changed code and run its focused test. Skip

- builds for prose-only edits; no change or still-applicable pass means no rerun.

- - **Realign:** reconcile the plan; test only a repair or a concrete uncertainty.

- - **Lint:** formatting and static analysis only.

- - **Rebase:** no tests when conflict-free; after conflicts, one focused test.

- - **Gate:** affected suites and automated acceptance checks once. Reuse only

- identical tracked/untracked content and the identical command plan.

- - **CI/release:** the full machine-runnable matrix and deployment checks.

- - **Demo/review:** the real user experience and people's judgment.

-

- Required checks run headless, without a display session, permission dialog or

- person. Use app builds and view/interaction tests for Desktop. An unavailable

- check goes to capable gate/CI or gets a headless equivalent; it never blocks

- an earlier Graph step. Actual build/test failures still need repair. Keep scratch

- check results to one line with command, result and any deferred owner.

- Do not rerun broader checks because another lifecycle phase began.

-

- Headless Swift view tests inspect production leaf views directly when a parent

- requires `@Environment` Observation objects; ViewInspector cannot inject those

- objects. Keep existing leaf views internal for `@testable` access rather than

- adding test-only constructors or mounting a window.

- Keep mounted terminal frame checks in `.requiresDisplay` suites.

-

- ## When to Mock

-

- Mock to isolate your code from things that shouldn't be part of unit tests:

- - **External systems**: Network calls, databases, file systems (when testing logic, not I/O)

- - **Side effects**: Sending emails, writing logs, spawning processes

- - **Slow operations**: Anything that would make tests take seconds instead of milliseconds

-

- Don't mock to verify internal wiring. If a test's assertions are just "did we call the mock with the right args?"—that's testing implementation, not behavior. The test will break when you refactor, even if the feature still works.

- ```python

- # Bad: testing that we called the mock correctly

- def test_send_notification():

- with patch("app.email.send") as mock_send:

- notify_user(user)

- mock_send.assert_called_once_with(user.email, ANY)

- # Good: mock the side effect, test the behavior

- def test_notify_user_returns_success():

- with patch("app.email.send"): # prevent actual email

- result = notify_user(user)

- assert result.success

- # Better: if possible, test without mocking

- def test_notification_message_format():

- msg = build_notification(user)

- assert user.name in msg.body

- ```

- If a test requires elaborate mock setup, it's usually a sign that either:

- 1. The code under test does too much (refactor it)

- 2. You're testing implementation rather than behavior (test something else)

- 3. This should be an integration test, not a unit test (move it)

- **Never reshape production code for tests.** If you're adding a factory trait, an interface, a constructor overload, or an extra parameter solely because tests need it, stop. The production code's shape should be dictated by production needs. Use closures, conditional compilation (`#[cfg(test)]`), or test-only modules — not abstractions that exist to satisfy test doubles.

- **No factory patterns.** Factory traits, abstract factories, and provider registries are almost always over-engineering. A function or a closure does the same job without the ceremony. If you need runtime dispatch, use an enum or a function pointer — not a trait with one method and one real implementation.

- Run a Mitchell Hashimoto-style simulated code review for each unit of work before calling it done. Use the spirit, not cosplay: simple interfaces, boring operational behavior, clear ownership, docs that match the code, and no abstraction that exists only to feel flexible.

-

- Ask hard questions:

- - Does the API map to the real thing, or to our implementation accident?

- - Is this dependency, config knob, or compatibility shim earning its keep?

- Record concrete findings in the PR notes or fix them immediately. Do not perform theater; the review earns its place only when it changes the work.

-

- # Pre-Commit Checklist

-

- Before committing, verify:

-

- **Python:**

- - [ ] No new `Args:`/`Returns:` docstrings on functions with clear types

- - [ ] No inline imports; all imports at top of file

-

- **Rust:**

- - [ ] `cargo fmt` passes

- - [ ] `cargo clippy --all-targets -- -D warnings` passes

- - [ ] Public types derive `Debug`

- - [ ] No `unwrap()` outside tests; use `expect("reason")`

-

- **Both:**

- - [ ] No `v2_`, `_old`, `_new`, `_backup` etc.; keep one implementation, use git for history

- - [ ] Mocks prevent side effects, not verify internal wiring

- - [ ] Tests assert on results, not mock calls

- - [ ] README changes don't duplicate source code

- - [ ] Existing READMEs updated if behavior changed

- Commit messages are documentation. Explain what changed and why, not line-by-line what you did:

- # Bad

- Add open_warp function

- Add open_cursor function

- Update cli.py to call new functions

- Fix import statement

-

- # Good

- Keep messages short—one sentence to one paragraph.

-

- Do not add AI attribution footers like "Generated with Claude Code" or "Co-Authored-By: Claude" to commits. The git history should read the same whether written by a person or AI.