Goal
Give the common Base Python preparation sequence and repeated runtime-package checks one owner in the existing setup helper boundaries, with explicit platform prerequisites and finalization left at callers.
Background
Repository-wide duplication review against f9c18f3294873cbbcda9acc7af7f1bc6b17eed45 (2026-09-17).
Three install entrypoints repeat virtualenv creation, pip upgrade, PyYAML/Click/base-cli installation, profile setup including dry-run branching, and project artifact setup. Linux and CI also repeat 30 normalized lines of venv/PyYAML/Click diagnostics. These are platform-neutral Base runtime responsibilities embedded in platform adapters.
Verified source locations:
Closed #1106 addressed setup/doctor probe sharing. This is the remaining install-sequence and runtime-package duplication after platform extraction, consistent with docs/setup-common-ownership.md.
This is a maintainability refactor. Similarity alone is not evidence of a production failure; any demonstrated differences are called out above.
Scope
Give the common Base Python preparation sequence and repeated runtime-package checks one owner in the existing setup helper boundaries, with explicit platform prerequisites and finalization left at callers.
Acceptance Criteria
- A single common sequence owns venv/package/profile/artifact ordering.
- Homebrew/Xcode/apt/gh prerequisites stay in their platform adapters.
- CI continues to omit user-config seeding while ordinary platform setup retains it.
- Preserve dry-run flags, check ordering and diagnostic messages, failure propagation and profile selection.
- Share the Linux/CI check block without changing macOS parallel-probe scheduling.
Validation
Run setup.bats, setup-common.bats, setup-command.bats and platform-relevant BATS cases. Use stubbed call traces for each platform and CI, dry-run and normal mode, and injected failures at pip/profile/artifact steps.
Run focused checks first, then the repository-required broader checks for the actual implementation. Preserve public command contracts and review .ai-context/ impact in the PR.
Non-Goals
Do not split sourceable shell libraries into topic fragments; do not merge platform providers; no change to standalone bootstrap/install dependencies.
Project Fields
- Status: Ready
- Priority: P2
- Area: Setup
- Initiative: Contract Hardening
- Size: M
- Milestone: Unscheduled; no release commitment is implied by this audit.
Agent Assignment
Implementation-ready scoped follow-up, assigned to codeforester. Follow AGENTS.md and docs/github-workflow.md: start through basectl gh issue start, use the canonical issue worktree, characterize current behavior before extraction, and open an issue-linked PR. Keep each refactor independently reviewable.
Goal
Give the common Base Python preparation sequence and repeated runtime-package checks one owner in the existing setup helper boundaries, with explicit platform prerequisites and finalization left at callers.
Background
Repository-wide duplication review against
f9c18f3294873cbbcda9acc7af7f1bc6b17eed45(2026-09-17).Three install entrypoints repeat virtualenv creation, pip upgrade, PyYAML/Click/base-cli installation, profile setup including dry-run branching, and project artifact setup. Linux and CI also repeat 30 normalized lines of venv/PyYAML/Click diagnostics. These are platform-neutral Base runtime responsibilities embedded in platform adapters.
Verified source locations:
cli/bash/commands/basectl/subcommands/setup_macos_homebrew.sh:551-575cli/bash/commands/basectl/subcommands/setup_linux_debian.sh:466-491cli/bash/commands/basectl/subcommands/setup_venv.sh:479-499cli/bash/commands/basectl/subcommands/setup_linux_debian.sh:278-309cli/bash/commands/basectl/subcommands/setup_venv.sh:443-474Closed #1106 addressed setup/doctor probe sharing. This is the remaining install-sequence and runtime-package duplication after platform extraction, consistent with
docs/setup-common-ownership.md.This is a maintainability refactor. Similarity alone is not evidence of a production failure; any demonstrated differences are called out above.
Scope
Give the common Base Python preparation sequence and repeated runtime-package checks one owner in the existing setup helper boundaries, with explicit platform prerequisites and finalization left at callers.
Acceptance Criteria
Validation
Run setup.bats, setup-common.bats, setup-command.bats and platform-relevant BATS cases. Use stubbed call traces for each platform and CI, dry-run and normal mode, and injected failures at pip/profile/artifact steps.
Run focused checks first, then the repository-required broader checks for the actual implementation. Preserve public command contracts and review
.ai-context/impact in the PR.Non-Goals
Do not split sourceable shell libraries into topic fragments; do not merge platform providers; no change to standalone bootstrap/install dependencies.
Project Fields
Agent Assignment
Implementation-ready scoped follow-up, assigned to
codeforester. FollowAGENTS.mdanddocs/github-workflow.md: start throughbasectl gh issue start, use the canonical issue worktree, characterize current behavior before extraction, and open an issue-linked PR. Keep each refactor independently reviewable.