Adds the `1.x` release channel (fixes only, last line with PowerShell support) to every channel table, and makes ckb-upgrade stop and ask before crossing a major version, offering the maintenance branch instead. D-0019 records the 2.0 plan: drop PowerShell, scripts stay in Python. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.4 KiB
| type | tldr | status | decided_on | decided_by | affects | confidence | quality | last_updated | freshness_window_days | retention |
|---|---|---|---|---|---|---|---|---|---|---|
| decision | 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. | accepted | 2026-11-11 | Michał Kopeć | .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 | 0.85 | 0.8 | 2026-11-11 | 365 | 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. Python as the single scripting runtime, interpreter resolution, the bash fallback and the per-skill degraded paths stand.
Context
D-0003 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
- Template 2.0.0 removes PowerShell support.
lint_quick.ps1is deleted; the PowerShell version comparison inckb-upgradeStep 2 and every "or the.ps1" mention go with it. Removing a shipped fallback is breaking, hence the major bump.kb_schema_versionis unaffected: the content contract stays 1.7. - 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 themcpmodule's containerentrypoint.sh, which runs inside the image, not on the user's machine. - The 1.x line continues on a
1.xbranch, 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 likemain/test/experimental: a KB tracks it throughbranch: 1.xinckb.yaml. ckb-upgradenever 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.ps1and 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-upgradetracks 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
mainlacks the major guard; its Step 5 still shows every changed file and the changelog row, and the deleted.ps1is visible there. - Fixes worth having on both lines are made on
1.xand merged forward intomain, or cherry-picked when the code has diverged.