Research Python + uv for shared scripts and native Windows support #168

Outcome

Research whether Darrow should gradually replace Bash with Python + uv for shared scripts, with native Windows support and more maintainable script logic as the main motivations. Deliver a recommendation on adoption and migration scope.

The current portable Bash baseline in docs/decisions/ADR-0005-use-portable-bash-facades-for-plugin-mechanics.md prioritizes default macOS/Linux environments without an additional language runtime. Repository development infrastructure is outside that plugin-runtime boundary. docs/decisions/ADR-0008-allow-python-and-uv-for-langfuse-observability.md already permits a contained Python + uv backend for Langfuse, while retaining a Bash launcher.

The direction discussed is to use Python + uv for new substantial helpers, migrate existing scripts incrementally, and retain Bash for small platform-specific glue. Keep independently installed plugins self-contained.

Done criteria

• Evaluate maintainability and portability against the current Bash baseline, distinguishing repository development scripts from plugin-shipped helpers.
• Assess uv as an explicit prerequisite, including Python provisioning, initial downloads, offline operation, standard-library usage, and locking external dependencies.
• Identify requirements for native Windows operation, including entrypoints, subprocess invocation, paths, file locking, and wrapped CLI behavior.
• Recommend a representative helper for an initial migration and validation on macOS, Linux, and native Windows before broader adoption.
• Record a recommendation on whether and how to proceed, including implications for ADR-0005, the Langfuse exception, and plugin independence.

Prioritized plugin rollout

The rollout starts with the shared authoring foundation, proves the runtime pattern on small deterministic renderers, then moves through provider and filesystem capabilities before the largest mutation/review/orchestration surfaces. Composition-only and skill-only plugins follow, and the deprecated reference pipeline remains last.

1. Establish and enforce repository-wide Python quality standards #172 — Establish repository-wide Python quality standards and upgrade darrow-observability-langfuse.
2. Upgrade darrow-skill-authoring for Python + uv plugin mechanics #175 — Upgrade darrow-skill-authoring and establish the reusable migration conventions.
3. Migrate darrow-discovery renderer to Python + uv #176 — Migrate darrow-discovery's frontier renderer.
4. Migrate darrow-verification renderer to Python + uv #177 — Migrate darrow-verification's assessment renderer.
5. Migrate darrow-tickets-github mechanics to Python + uv #178 — Migrate darrow-tickets-github mechanics.
6. Migrate darrow-decisions mechanics to Python + uv #179 — Migrate darrow-decisions mechanics.
7. Migrate darrow-information-architecture mechanics to Python + uv #180 — Migrate darrow-information-architecture mechanics.
8. Migrate darrow-git mechanics to Python + uv #181 — Migrate darrow-git mechanics after the lower-risk subprocess and filesystem patterns are proven.
9. Migrate darrow-review mechanics to Python + uv #182 — Migrate darrow-review mechanics.
10. Migrate darrow-adaptive-delivery mechanics to Python + uv #183 — Migrate darrow-adaptive-delivery mechanics without expanding orchestration authority.
11. Upgrade darrow-ticket-to-pr for the migrated plugin stack #184 — Upgrade darrow-ticket-to-pr composition against the migrated stack.
12. Certify darrow-explanation for the Python + uv plugin baseline #185 — Certify scriptless darrow-explanation under the final baseline.
13. Certify darrow-readiness-gate for the Python + uv plugin baseline #186 — Certify scriptless darrow-readiness-gate under the final baseline.
14. Certify darrow-tdd for the Python + uv plugin baseline #187 — Certify scriptless darrow-tdd under the final baseline.
15. Preserve darrow-ticket-pipeline under the Python + uv rollout #188 — Preserve deprecated darrow-ticket-pipeline as the final benchmark/reference audit.

Migration blueprint

Use the implementation merged in PR #173 as the default blueprint for Python + uv plugin mechanics. Reuse its self-contained package layout, committed uv lock, runtime/development dependency separation, python-packages.txt inventory, Ruff and strict mypy gates, separate 95% line and branch coverage gates, and fresh copied-artifact validation. Extend that pattern with native-Windows fresh-artifact validation where this rollout requires Windows support. Document any plugin-specific deviation explicitly instead of introducing a competing convention.