Convert design specs to ADRs

[kindermax]

Summary

• Promote dependency failure tree and remote config design specs into numbered ADRs
• Remove docs/specs and update the dependency failure plan link
• Add changelog entry for the docs migration

Validation

• git diff --cached --check

Summary by Sourcery

Promote existing design specifications for dependency failure trees and remote configs into formal ADR documents and update references.

Enhancements:

• Update the dependency failure plan document to reference the new ADR for dependency failure trees instead of the old design spec.

Documentation:

• Add ADR-0002 describing dependency failure tree error reporting and ADR-0003 describing remote configs with local caching, replacing the previous design spec documents.
• Update the docs changelog to record the migration of design specs into ADRs.
• Remove the superseded design spec files for dependency failure trees and remote configs.

[sourcery-ai]

Reviewer's Guide

Promotes two existing design specs (dependency failure tree and remote configs) into numbered ADR documents, updates references and changelog, and removes the original spec files.

Flow diagram for migrating design specs to ADR documents

flowchart TD
    Specs[Design_specs]
    ADRs[ADRs]

    Specs -->|Promote_dependency_failure_tree| ADR_0002[ADR_0002_dependency_failure_tree]
    Specs -->|Promote_remote_config_design| ADR_0003[ADR_0003_remote_configs]

    ADR_0002 -->|Linked_from_plan| Plan_dependency_failure_tree[Plan_2026_03_14]
    ADRs -->|Mentioned_in| Docs_changelog[Docs_changelog_Unreleased]

    Specs -. Removed .-> Removed_specs[Deleted_spec_files]

Loading

File-Level Changes

Change	Details	Files
Promote the dependency failure tree design spec into ADR-0002 and wire it into existing docs.	Add ADR-0002 capturing the dependency failure tree design, context, decision, consequences, and related implementation references. Update the dependency failure plan document to reference the new ADR instead of the old design spec.	docs/adr/0002-dependency-failure-tree.md docs/plans/2026-03-14-dependency-failure-tree.md
Promote the remote configs design spec into ADR-0003.	Add ADR-0003 describing remote configs with local caching, including context, decision details, and consequences.	docs/adr/0003-remote-configs.md
Update general documentation to reflect the ADR migration and remove obsolete specs.	Add a changelog entry noting the conversion of design specs into ADRs. Delete the legacy dependency failure tree and remote config design spec documents.	docs/docs/changelog.md docs/specs/2026-03-13-dependency-failure-tree-design.md docs/specs/2026-06-13-remote-config-design.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 1 issue

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="docs/adr/0002-dependency-failure-tree.md" line_range="59" />
<code_context>
+## 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.
</code_context>
<issue_to_address>
**nitpick (typo):** Consider using a more standard spelling for "unwrap-able".

"Unwrap-able" is unconventional; consider "unwrappable" or "unwrapable" (without the hyphen) for a more standard spelling.

```suggestion
- **Positive:** The original error remains unwrappable, so existing error handling and exit-code propagation continue to work.
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

nitpick (typo): Consider using a more standard spelling for "unwrap-able".

"Unwrap-able" is unconventional; consider "unwrappable" or "unwrapable" (without the hyphen) for a more standard spelling.

Suggested change

	- **Positive:** The original error remains unwrap-able, so existing error handling and exit-code propagation continue to work.
	- **Positive:** The original error remains unwrappable, so existing error handling and exit-code propagation continue to work.