Convert design specs to ADRs

docs/adr/0002-dependency-failure-tree.md

@@ -0,0 +1,72 @@
+# ADR-0002 — Render Project command failures as a dependency tree
+
+**Date:** 2026-06-14
+**Status:** Accepted
+
+## Context
+
+This decision was originally captured as a design spec on 2026-03-13 and later promoted to an ADR.
+
+When `lets` ran a **Project command** with a `depends` chain and a dependency failed, the error output only named the innermost failing command:
+
+```text
+failed to run command 'lint': exit status 1
+```
+
+Users could not see which parent commands triggered that failure or how deep in the **Dependency chain** execution stopped. The same ambiguity existed for single-command failures because the error carried no structured command context.
+
+The fix needed to work for both serial and parallel command execution paths without changing the child process exit code that `lets` returns.
+
+## Decision
+
+Carry command-chain context through executor errors with a `DependencyError` type in `internal/executor`.
+
+`DependencyError` stores:
+
+- `Chain []string`: the failing **Dependency chain**, outermost-first, for example `[]string{"deploy", "build", "lint"}`.
+- `Err error`: the original execution error.
+
+It delegates `Error()` and `Unwrap()` to the original error, and its `ExitCode()` preserves the exit code from the innermost `ExecuteError` when one exists.
+
+Add a `prependToChain(name, err)` helper at command boundaries:
+
+- If `err` is already a `DependencyError`, return a new `DependencyError` with `name` prepended and the original cause preserved.
+- Otherwise, wrap `err` in a single-node `DependencyError`.
+
+Both `execute()` and `executeParallel()` call `prependToChain` for command-scoped error paths:
+
+- command initialization (`initCmd`)
+- dependency execution (`executeDepends`)
+- command script execution (`runCmd`)
+- persisted-checksum writes (`persistChecksum`)
+
+The root **Init script** is intentionally excluded because it is not tied to a **Project command** name.
+
+Render the chain in the CLI error renderer as a themed `command tree:` section, with the failing leaf annotated:
+
+```text
+command tree:
+    └─ deploy
+      └─ build
+        └─ lint  <-- failed here
+```
+
+For non-terminal output, keep the plain error text path.
+
+## Consequences
+
+- **Positive:** Users see the full command context for dependency failures and single-command failures.
+- **Positive:** The original error remains unwrap-able, so existing error handling and exit-code propagation continue to work.
+- **Positive:** Serial and parallel executor paths share the same command-boundary wrapping rule.
+- **Neutral:** Command execution failures now surface as `DependencyError` values at higher layers.
+- **Neutral:** Failures inside a parallel `cmd` array are attributed to the owning **Project command**, not to an individual shell fragment.
+- **Negative:** The error renderer now depends on executor-specific error structure to show the command tree.
+
+## Related implementation
+
+- `internal/executor/dependency_error.go`
+- `internal/executor/executor.go`
+- `internal/cmd/error.go`
+- `internal/executor/dependency_error_test.go`
+- `internal/cmd/help_golden_test.go`
+- `tests/dependency_failure_tree.bats`

docs/adr/0003-remote-configs.md

@@ -0,0 +1,70 @@
+# ADR-0003 — Support Remote configs with local caching
+
+**Date:** 2026-06-14
+**Status:** Accepted
+
+## Context
+
+This decision was originally captured as a design spec on 2026-06-13 and later promoted to an ADR. It originated from Issue [#351](https://github.com/lets-cli/lets/issues/351).
+
+`lets` could load a local **Project config** from `lets.yaml`, but users also wanted to run reusable project workflows published at a URL:
+
+```bash
+lets -c https://example.com/lets.yaml build
+```
+
+A **Remote config** needed different behavior from a local file:
+
+- avoid re-downloading unchanged configs on every invocation
+- let users force a refresh when the remote source changes
+- preserve the invocation directory as the **Work dir** for commands
+- share HTTP download behavior with **Remote mixins** instead of duplicating it
+- fail safely when the network is unavailable
+
+## Decision
+
+Treat a root `--config` / `-c` value that starts with `http://` or `https://` as a **Remote config**.
+
+Add a root `--no-cache` flag. For remote sources, this asks lets to re-download instead of using an existing cached copy. The same no-cache choice is passed through config loading so **Remote mixins** refresh consistently with **Remote configs**.
+
+Cache downloaded Remote configs at:
+
+```text
+~/.config/lets/remote-configs/<sha256(url)>.yaml
+```
+
+The URL hash is the cache identity. Cache writes are atomic: write a sibling temp file, set file mode, then rename into place.
+
+Remote config loading follows this flow:
+
+1. Without `--no-cache`, use the cache if present.
+2. Otherwise download the URL, write it to the cache, then load the cached file.
+3. If the download fails and a cache file exists, warn and fall back to the cached file.
+4. If the download fails with no cache file, return an error.
+
+Load the cached YAML through the same config validation and setup path as local Project configs, but set the config **Work dir** and `.lets` directory from the invocation CWD. Commands from a Remote config therefore run from where the user invoked `lets`, unless a command declares `work_dir`.
+
+Extract shared HTTP download behavior into `internal/fetch` so Remote configs and Remote mixins use the same implementation. `fetch.Download` accepts only `text/plain`, `text/yaml`, `text/x-yaml`, `application/yaml`, and `application/x-yaml`; reports non-2xx responses; supports progress observers; and is cancellable through context.
+
+If `LETS_CONFIG_DIR` is set while using a Remote config URL, warn and ignore it because discovery relative to a local config directory does not apply.
+
+## Consequences
+
+- **Positive:** Users can publish and consume shared Project configs by URL.
+- **Positive:** Cached configs make repeated invocations fast and provide an offline fallback.
+- **Positive:** `--no-cache` gives users a direct way to refresh Remote configs and Remote mixins.
+- **Positive:** Remote config downloads and Remote mixin downloads share one fetch implementation and progress-reporting path.
+- **Neutral:** A cached file that no longer parses produces a normal config error with guidance to retry using `--no-cache`.
+- **Neutral:** The invocation CWD, not the cache directory, defines the default Work dir for Remote config commands.
+- **Negative:** Remote configs are executable project workflow definitions; users must trust the URL they run.
+- **Negative:** The cache is keyed only by URL. Different content at the same URL replaces the prior cached config when refreshed.
+
+## Related implementation
+
+- `internal/cli/cli.go`
+- `internal/cmd/root.go`
+- `internal/config/load.go`
+- `internal/config/config/mixin.go`
+- `internal/fetch/fetch.go`
+- `internal/config/load_test.go`
+- `internal/fetch/fetch_test.go`

docs/docs/changelog.md

@@ -5,6 +5,7 @@ title: Changelog
 
 ## [Unreleased](https://github.com/lets-cli/lets/releases/tag/v0.0.X)
 
+* `[Docs]` Convert design specs into ADRs.
 * `[Added]` Add `lets self config path` and `lets self config edit` for user settings. Issue [#370](https://github.com/lets-cli/lets/issues/370)
 * `[Added]` Show interactive download progress for remote configs and remote mixins. Issue [#360](https://github.com/lets-cli/lets/issues/360)
 * `[Fixed]` Make `--no-cache` re-download remote mixins for local and remote configs. Issue [#365](https://github.com/lets-cli/lets/issues/365)

docs/plans/2026-03-14-dependency-failure-tree.md

@@ -8,7 +8,7 @@
 
 **Tech Stack:** Go stdlib `errors`, `fmt`, `io`, `strings`; `github.com/fatih/color` v1.16.0 (already in `go.mod`) for red highlight; `testing` package for unit tests; bats-core + bats-assert for integration tests.
 
-**Spec:** `docs/specs/2026-03-13-dependency-failure-tree-design.md`
+**ADR:** `docs/adr/0002-dependency-failure-tree.md`
 
 ---