--- type: decision tldr: Template 2.0.0 drops PowerShell (lint_quick.ps1 and every PowerShell snippet); scripts the template and its modules ship stay in Python; the 1.x line continues on a `1.x` maintenance branch for fixes, and ckb-upgrade never crosses a major version without asking. status: accepted decided_on: 2026-11-11 decided_by: Michał Kopeć affects: .agents/skills/ckb-lint/, .agents/skills/ckb-upgrade/SKILL.md, .agents/skills/ckb-init/SKILL.md, .agents/skills/ckb-sync-changes/SKILL.md, AGENTS.md, README.md, docs/MANUAL.md, docs/CHANGELOG.md, VERSION confidence: 0.85 quality: 0.8 last_updated: 2026-11-11 freshness_window_days: 365 retention: high --- # D-0019 — 2.0 drops PowerShell; 1.x continues on a maintenance branch **Status:** Accepted · **Decided:** 2026-11-11 · **Deciders:** Michał Kopeć > Supersedes only the PowerShell half of [D-0003](0003-python-runtime-with-degraded-fallbacks.md). > Python as the single scripting runtime, interpreter resolution, the bash > fallback and the per-skill degraded paths stand. ## Context [D-0003](0003-python-runtime-with-degraded-fallbacks.md) shipped two native fallbacks for the session-start check, `lint_quick.sh` and `lint_quick.ps1`, and said any change to checks 1, 2, 12 (later also 15) must land in both. The smoke test diffs the bash copy against `lint_report.py --quick`; the PowerShell copy has never run in CI and is "reviewed by hand until a Windows runner exists". No runner exists, and an open thread to test it on a machine with PowerShell has gone unclosed. Each lint change that touched the fallback paid for a copy nobody could verify. Windows users are not left without a path: Python installs in one command (`winget`, the Store, python.org), and Git for Windows, which the KB already needs, ships bash, so `lint_quick.sh` runs there too. ## Decision 1. **Template 2.0.0 removes PowerShell support.** `lint_quick.ps1` is deleted; the PowerShell version comparison in `ckb-upgrade` Step 2 and every "or the `.ps1`" mention go with it. Removing a shipped fallback is breaking, hence the major bump. `kb_schema_version` is unaffected: the content contract stays 1.7. 2. **Scripts stay in Python.** Every script the template runs, in skills and in modules, is Python 3.8+ standard library. A module may need other tools (git, Docker, `yt-dlp`), but the scripts it carries are Python. Two non-Python files stay as named exceptions: `lint_quick.sh`, the no-Python fallback (it exists *because* Python is missing), and the `mcp` module's container `entrypoint.sh`, which runs inside the image, not on the user's machine. 3. **The 1.x line continues on a `1.x` branch**, cut from 1.28.1. It gets fixes only, no new features, and is the last line with PowerShell support. It is a release channel like `main`/`test`/`experimental`: a KB tracks it through `branch: 1.x` in `ckb.yaml`. 4. **`ckb-upgrade` never crosses a major version silently.** When upstream's major is higher, it quotes the breaking part of the changelog and asks: take the new major, or switch to the maintenance branch. Never from a routine or batch run. This landed in 1.28.1 so that a KB upgrading from 1.28.1 onward already has the guard before it meets 2.0. ## Alternatives considered - **Keep `lint_quick.ps1` and add a Windows CI runner.** Fixes the verification gap, but keeps the cost of a third implementation for a fallback that only serves people without Python, who can install it in one command. - **Drop the bash fallback too, making the rule "all scripts are Python" absolute.** Considered and declined: bash is tested against the Python reference on every smoke run, so it costs little, and it keeps the session-start check alive on a machine with no Python. - **No maintenance branch; tell 1.x users to pin a tag.** A tag gets no fixes, and `ckb-upgrade` tracks branches, not tags. ## Consequences - Windows users without Python lose the native session-start fallback unless they run it under Git Bash; the agent falls through to the manual checklist otherwise. - Changes to the quick checks now land in two places (Python, bash), both covered by the smoke test. - A KB on 1.28.0 or older upgrading straight from `main` lacks the major guard; its Step 5 still shows every changed file and the changelog row, and the deleted `.ps1` is visible there. - Fixes worth having on both lines are made on `1.x` and merged forward into `main`, or cherry-picked when the code has diverged.