devstuff 1.17.0__tar.gz → 1.18.0__tar.gz

{devstuff-1.17.0 → devstuff-1.18.0}/.github/workflows/test-installs.yml

@@ -52,6 +52,7 @@ jobs:
       matrix:
         tool:
           - aws
+          - commitizen  # uvx tool, requires uv
           - eza
           - gh
           - git-lfs

{devstuff-1.17.0 → devstuff-1.18.0}/CHANGELOG.md

@@ -1,3 +1,9 @@
+## v1.18.0 (2026-08-01)
+
+### Features
+
+- **configure**: add commitizen tool and configuration wizard
+
 ## v1.17.0 (2026-07-31)
 
 ### Feat

{devstuff-1.17.0 → devstuff-1.18.0}/CLAUDE.md

@@ -173,8 +173,9 @@ ones tools already have.
 ## Configurators (`configure/`) — tool-specific wizards, deliberately *not* catalog-driven
 
 `src/dev_setup/configure/` holds per-tool setup wizards (`devstuff configure <tool>`), registered
-in a `CONFIGURATORS` dict keyed by catalog tool key. `starship` is the first one:
-`configure/starship/{model,render,preview,wizard}.py`.
+in a `CONFIGURATORS` dict keyed by catalog tool key. There are two:
+`configure/starship/{model,render,preview,wizard}.py` and
+`configure/commitizen/{model,render,detect,validate,wizard}.py`.
 
 **Why this one breaks the YAML-catalog rule.** Installation generalises into ~7 mechanisms, which
 is what makes `GenericTool` possible. Configuration does not: starship's config is a TOML file of
@@ -244,8 +245,46 @@ or palette is one entry; no other file changes.
   the ordinary catalog path (`nerd-font` in `tools.yaml` → `install_cmd.install_by_key`), never a
   private download (SD-10).
 
-Not yet built: configurators for anything other than starship, and round-tripping an existing
-hand-edited config back into wizard state (the timestamped backup is the safety net instead).
+**Within the commitizen configurator, the object being configured is a list of commit types, not
+a settings sheet.** `TYPES` in `model.py` is ordered (declaration order *is* prompt order, changelog
+order and regex-alternation order), and `render.py` derives all nine `cz_customize` settings from
+it — so adding a type is one `ChangeType` record and it reaches `bump_pattern`, `bump_map`,
+`schema_pattern`, `change_type_map`, `change_type_order`, `commit_parser` and `questions` with no
+other edit. Full reasoning in `docs/specs/commitizen-config/`.
+
+**Things learned from the real binary — don't "simplify" these away:**
+- `bump_map` is an **ordered** map and commitizen `break`s at the first key that `re.match`es, so
+  the two breaking-change rules (`^.+!$`, `^BREAKING[\-\ ]CHANGE`) must be emitted first. Reorder
+  them and `feat(api)!:` silently ships as a MINOR.
+- What `bump_map`'s keys are matched against is **group 1 of `bump_pattern`** (`feat(api)!`), not
+  the commit message. That is why `^.+!$` works at all, and why every selected type belongs in the
+  pattern even when it has no map entry.
+- `schema_pattern` must always accept the `bump:` prefix (`ALWAYS_ACCEPTED` in `model.py`):
+  `cz bump` writes its own commit with that prefix, and `cz check --rev-range` over a release
+  otherwise rejects commitizen's own commit. `cz_conventional_commits` accepts `bump` for exactly
+  this reason without ever offering it in the picker.
+- `commit_parser`'s trailing `|\w+!` alternative is load-bearing: it is what keeps `docs!: …` (a
+  breaking change on a type with no changelog section) in the release notes at all. Verified — it
+  lands in an unlabelled group rather than vanishing.
+- The `BREAKING CHANGE` changelog heading only collects commits with a **footer**. A `feat!:` still
+  bumps the major but is written up under Features, because that is the type it declared.
+- Regexes are emitted as TOML **literal** strings (`'…'`) so no backslash needs doubling;
+  `message_template` and `schema` are the exceptions (they carry real newlines, so they are basic
+  strings). A user-supplied value containing a quote falls back to a basic string automatically.
+- `config_path()` mirrors `commitizen.config.read_cfg`: search order *and* the rule that a file
+  without a `commitizen` section doesn't count — otherwise every Python project on disk looks
+  already-configured because it has a `pyproject.toml`.
+- The `pyproject.toml` splice is line-based, so it verifies itself by parsing the result back and
+  comparing the settings; a mismatch returns `None` and the caller writes `.cz.toml` instead. Don't
+  replace that check with reasoning about which files it can handle.
+- `validate.py` is the "measured, not assumed" half: it replays commits through the real
+  `cz bump --dry-run` in a throwaway repo. It runs on an explicit menu action plus once at save
+  time — not on every redraw (~3s, unlike starship's millisecond preview) — and a disagreement
+  *warns*, it never vetoes a save. Keep that distinction in the comments.
+
+Not yet built: configurators for anything other than starship and commitizen, and round-tripping an
+existing hand-edited config back into wizard state (the timestamped backup is the safety net
+instead).
 
 ## Specs (`docs/specs/`)
 

{devstuff-1.17.0 → devstuff-1.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devstuff
-Version: 1.17.0
+Version: 1.18.0
 Summary: Development environment setup CLI for Linux
 Project-URL: Repository, https://github.com/thesawdawg/dev-setup-py
 Author-email: Sawyer <sawyerksu@gmail.com>
@@ -203,8 +203,104 @@ devstuff configure starship --output /tmp/try.toml   # write elsewhere, leave th
 
 | Tool | What it configures |
 |------|-------------------|
+| `commitizen` | Commit types, what each one bumps, git tags, and changelog sections |
 | `starship` | Prompt style, colour palette, which sections appear, and layout |
 
+#### Commitizen wizard
+
+Commitizen needs a config file before it does anything, and everything past its built-in
+Conventional Commits rules means `cz_customize` — nine coupled regexes where `bump_map`'s keys
+are matched against **group 1** of `bump_pattern`, the two breaking-change rules have to come
+*first* because commitizen stops at the first key that matches, and `schema_pattern` has to
+accept whatever `message_template` produces. Get the order wrong and `feat(api)!:` quietly ships
+as a minor release.
+
+The wizard asks about commit types and version rules, and derives all nine settings from the
+answers:
+
+| Step | Options |
+|------|---------|
+| **Convention** | `cz_conventional_commits` (commitizen's fixed rules — nothing to configure) · `cz_customize` (your types, your bump rules) |
+| **Commit types** | Checkbox over `feat`, `fix`, `refactor`, `perf`, `docs`, `style`, `test`, `build`, `ci` (all on, matching Conventional Commits) plus `chore`, `revert`, `deps`, `security` — and you can add your own |
+| **Per type** | What it bumps (`MAJOR` / `MINOR` / `PATCH` / no release), whether it appears in the changelog, under which heading, and its hotkey in `cz commit` |
+| **Versioning** | Where the version lives (`commitizen`, `scm`, `pep621`, `uv`, `poetry`, `cargo`, `npm`, `composer`) · scheme (`semver`, `semver2`, `pep440`) · tag format · other files carrying the version |
+| **Release** | Changelog on bump · `0.x` mode · annotated tags · GPG signing · incremental changelog · prerelease merging · `allow_abort` · hotkeys · changelog file · bump commit message |
+| **Prompt** | Which questions `cz commit` asks — scope, body, footer |
+| **Destination** | `pyproject.toml` (spliced in place) or a standalone `.cz.toml` |
+
+The custom branch **starts as an exact copy of Conventional Commits** — the built-in type table
+reproduces `commitizen.defaults.BUMP_MAP` and its picker, read out of the installed package and
+pinned by a test. Switching to custom to add one type does not cost you the convention.
+
+Before it asks anything, the wizard reads the project: git root, any existing commitizen config
+(in commitizen's own search order, ignoring files without a `commitizen` section), the version
+provider and current version from `pyproject.toml`/`package.json`/`Cargo.toml`/`composer.json`,
+the latest git tag, and an existing changelog.
+
+The review screen shows a sample `cz commit` message, the bump table, and the changelog sections:
+
+```
+  what each type does to 1.4.2
+
+  commit                       increment  new version
+  feat: …                      MINOR      1.5.0
+  fix: …                       PATCH      1.4.3
+  docs: …                      —          1.4.2
+  feat!: …                     MAJOR      2.0.0
+  BREAKING CHANGE: … (footer)  MAJOR      2.0.0
+```
+
+**That table is checked against the real thing.** "Check these rules against the real cz" builds
+a throwaway git repo tagged at 1.4.2, replays one commit per bump level plus both breaking forms
+through `cz bump --dry-run`, and reports whether commitizen agrees rule by rule. The same check
+runs automatically before saving — a disagreement is reported and asks for confirmation, but
+never blocks the save. "Preview a generated changelog" runs the real `cz changelog --dry-run`
+over one sample commit per type. Without `cz` installed the wizard still works; the checks say so
+rather than failing.
+
+On save:
+
+- Into `pyproject.toml`, every `[tool.commitizen…]` table is replaced and **the rest of the file
+  is left byte for byte**. The result is parsed back and compared to what was meant; if it does
+  not match, the write falls back to a standalone `.cz.toml` and the original is untouched.
+- Any existing file is copied to `<name>.bak.<timestamp>` first, and a config that wasn't written
+  by this wizard asks before being replaced.
+- If more than one commitizen config now exists, you're told which one commitizen will actually
+  read — `.cz.toml` beats `pyproject.toml`, so a new dotfile can silently shadow settings you
+  forgot about.
+- In a git repo with no `commit-msg` hook, you're offered one running `cz check`. An existing
+  hook is never replaced.
+
+The output is meant to be hand-edited afterwards: commented, ordered, and with regexes written as
+TOML literal strings so `^((BREAKING[\-\ ]CHANGE|feat)(\(.+\))?!?):` reads as itself instead of
+with every backslash doubled.
+
+```toml
+# Commitizen configuration
+# Generated by `devstuff configure commitizen` — edit freely, or re-run the wizard.
+# Convention: Custom types and bump rules · Types: feat, fix, docs, deps
+# Option reference: https://commitizen-tools.github.io/commitizen/config/
+[tool.commitizen]
+name = 'cz_customize'
+version_provider = 'pep621'
+version_scheme = 'pep440'
+tag_format = 'v$version'
+update_changelog_on_bump = true
+# …
+
+# Prefix -> version increment. Order matters: commitizen stops at the first
+# key that matches, so the two breaking-change rules have to lead.
+[tool.commitizen.customize.bump_map]
+'^.+!$' = 'MAJOR'
+'^BREAKING[\-\ ]CHANGE' = 'MAJOR'
+'^feat' = 'MINOR'
+'^fix' = 'PATCH'
+'^deps' = 'PATCH'
+```
+
+Design notes, including why this one isn't catalog-driven and why the checks warn rather than
+veto: [`docs/specs/commitizen-config/`](docs/specs/commitizen-config/).
+
 #### Starship prompt wizard
 
 Four questions, with the prompt re-rendered after each one:
@@ -685,6 +781,7 @@ Optional utilities you may want on some machines.
 | Key | Name | Description | Help |
 |-----|------|-------------|------|
 | `aws` | AWS CLI | Amazon Web Services CLI v2 | `aws help` |
+| `commitizen` | Commitizen | Conventional-commit prompt, semantic version bumping, and changelog generation (`devstuff configure commitizen`) | `cz --help` |
 | `eza` | eza | Modern ls replacement with git status, icons, and tree view | `eza --help` |
 | `gh` | GitHub CLI | GitHub's official CLI | `gh --help` |
 | `htop` | htop | Interactive process and resource monitor | `man htop` |

{devstuff-1.17.0 → devstuff-1.18.0}/README.md

@@ -176,8 +176,104 @@ devstuff configure starship --output /tmp/try.toml   # write elsewhere, leave th
 
 | Tool | What it configures |
 |------|-------------------|
+| `commitizen` | Commit types, what each one bumps, git tags, and changelog sections |
 | `starship` | Prompt style, colour palette, which sections appear, and layout |
 
+#### Commitizen wizard
+
+Commitizen needs a config file before it does anything, and everything past its built-in
+Conventional Commits rules means `cz_customize` — nine coupled regexes where `bump_map`'s keys
+are matched against **group 1** of `bump_pattern`, the two breaking-change rules have to come
+*first* because commitizen stops at the first key that matches, and `schema_pattern` has to
+accept whatever `message_template` produces. Get the order wrong and `feat(api)!:` quietly ships
+as a minor release.
+
+The wizard asks about commit types and version rules, and derives all nine settings from the
+answers:
+
+| Step | Options |
+|------|---------|
+| **Convention** | `cz_conventional_commits` (commitizen's fixed rules — nothing to configure) · `cz_customize` (your types, your bump rules) |
+| **Commit types** | Checkbox over `feat`, `fix`, `refactor`, `perf`, `docs`, `style`, `test`, `build`, `ci` (all on, matching Conventional Commits) plus `chore`, `revert`, `deps`, `security` — and you can add your own |
+| **Per type** | What it bumps (`MAJOR` / `MINOR` / `PATCH` / no release), whether it appears in the changelog, under which heading, and its hotkey in `cz commit` |
+| **Versioning** | Where the version lives (`commitizen`, `scm`, `pep621`, `uv`, `poetry`, `cargo`, `npm`, `composer`) · scheme (`semver`, `semver2`, `pep440`) · tag format · other files carrying the version |
+| **Release** | Changelog on bump · `0.x` mode · annotated tags · GPG signing · incremental changelog · prerelease merging · `allow_abort` · hotkeys · changelog file · bump commit message |
+| **Prompt** | Which questions `cz commit` asks — scope, body, footer |
+| **Destination** | `pyproject.toml` (spliced in place) or a standalone `.cz.toml` |
+
+The custom branch **starts as an exact copy of Conventional Commits** — the built-in type table
+reproduces `commitizen.defaults.BUMP_MAP` and its picker, read out of the installed package and
+pinned by a test. Switching to custom to add one type does not cost you the convention.
+
+Before it asks anything, the wizard reads the project: git root, any existing commitizen config
+(in commitizen's own search order, ignoring files without a `commitizen` section), the version
+provider and current version from `pyproject.toml`/`package.json`/`Cargo.toml`/`composer.json`,
+the latest git tag, and an existing changelog.
+
+The review screen shows a sample `cz commit` message, the bump table, and the changelog sections:
+
+```
+  what each type does to 1.4.2
+
+  commit                       increment  new version
+  feat: …                      MINOR      1.5.0
+  fix: …                       PATCH      1.4.3
+  docs: …                      —          1.4.2
+  feat!: …                     MAJOR      2.0.0
+  BREAKING CHANGE: … (footer)  MAJOR      2.0.0
+```
+
+**That table is checked against the real thing.** "Check these rules against the real cz" builds
+a throwaway git repo tagged at 1.4.2, replays one commit per bump level plus both breaking forms
+through `cz bump --dry-run`, and reports whether commitizen agrees rule by rule. The same check
+runs automatically before saving — a disagreement is reported and asks for confirmation, but
+never blocks the save. "Preview a generated changelog" runs the real `cz changelog --dry-run`
+over one sample commit per type. Without `cz` installed the wizard still works; the checks say so
+rather than failing.
+
+On save:
+
+- Into `pyproject.toml`, every `[tool.commitizen…]` table is replaced and **the rest of the file
+  is left byte for byte**. The result is parsed back and compared to what was meant; if it does
+  not match, the write falls back to a standalone `.cz.toml` and the original is untouched.
+- Any existing file is copied to `<name>.bak.<timestamp>` first, and a config that wasn't written
+  by this wizard asks before being replaced.
+- If more than one commitizen config now exists, you're told which one commitizen will actually
+  read — `.cz.toml` beats `pyproject.toml`, so a new dotfile can silently shadow settings you
+  forgot about.
+- In a git repo with no `commit-msg` hook, you're offered one running `cz check`. An existing
+  hook is never replaced.
+
+The output is meant to be hand-edited afterwards: commented, ordered, and with regexes written as
+TOML literal strings so `^((BREAKING[\-\ ]CHANGE|feat)(\(.+\))?!?):` reads as itself instead of
+with every backslash doubled.
+
+```toml
+# Commitizen configuration
+# Generated by `devstuff configure commitizen` — edit freely, or re-run the wizard.
+# Convention: Custom types and bump rules · Types: feat, fix, docs, deps
+# Option reference: https://commitizen-tools.github.io/commitizen/config/
+[tool.commitizen]
+name = 'cz_customize'
+version_provider = 'pep621'
+version_scheme = 'pep440'
+tag_format = 'v$version'
+update_changelog_on_bump = true
+# …
+
+# Prefix -> version increment. Order matters: commitizen stops at the first
+# key that matches, so the two breaking-change rules have to lead.
+[tool.commitizen.customize.bump_map]
+'^.+!$' = 'MAJOR'
+'^BREAKING[\-\ ]CHANGE' = 'MAJOR'
+'^feat' = 'MINOR'
+'^fix' = 'PATCH'
+'^deps' = 'PATCH'
+```
+
+Design notes, including why this one isn't catalog-driven and why the checks warn rather than
+veto: [`docs/specs/commitizen-config/`](docs/specs/commitizen-config/).
+
 #### Starship prompt wizard
 
 Four questions, with the prompt re-rendered after each one:
@@ -658,6 +754,7 @@ Optional utilities you may want on some machines.
 | Key | Name | Description | Help |
 |-----|------|-------------|------|
 | `aws` | AWS CLI | Amazon Web Services CLI v2 | `aws help` |
+| `commitizen` | Commitizen | Conventional-commit prompt, semantic version bumping, and changelog generation (`devstuff configure commitizen`) | `cz --help` |
 | `eza` | eza | Modern ls replacement with git status, icons, and tree view | `eza --help` |
 | `gh` | GitHub CLI | GitHub's official CLI | `gh --help` |
 | `htop` | htop | Interactive process and resource monitor | `man htop` |

{devstuff-1.17.0 → devstuff-1.18.0}/docs/specs/README.md

@@ -40,3 +40,4 @@ They are most useful when they capture:
 |---------|--------|
 | [`agent/`](agent/) — `devstuff agent`, the local-model agent | Complete (v1) |
 | [`starship-config/`](starship-config/) — `devstuff configure starship`, the prompt wizard | Complete (v1) |
+| [`commitizen-config/`](commitizen-config/) — `devstuff configure commitizen`, the commit-convention and bump-rule wizard | Complete (v1) |

devstuff-1.18.0/docs/specs/commitizen-config/development-plan.md

@@ -0,0 +1,80 @@
+# Development Plan: `devstuff configure commitizen`
+
+**Date:** 2026-07-31
+**Status:** Milestones 1–5 complete
+
+---
+
+## Milestones
+
+| # | Milestone | Deliverable | Done when |
+|---|-----------|-------------|-----------|
+| 1 | Catalog entry | `commitizen` in `src/dev_setup/tools.yaml` (`type: uvx`), CI matrix row, README table | `devstuff install commitizen` puts `cz` on the PATH; `devstuff list` shows its version |
+| 2 | Data model | `configure/commitizen/model.py` — `ChangeType`, the ordered `TYPES` table, providers/schemes/tag formats, `CommitizenConfig` | Defaults reproduce `commitizen.defaults.BUMP_MAP` and the conventional picker, with no I/O |
+| 3 | Emitter | `configure/commitizen/render.py` — the nine derived rules, `to_toml()`, `splice_pyproject()` | Output parses under `tomllib` for every convention × provider; splicing this repo's own `pyproject.toml` leaves every other table byte for byte |
+| 4 | Live check | `configure/commitizen/validate.py` — sandbox repo, `cz bump --dry-run` replay, `cz check`, `cz changelog --dry-run` | Seven configs replay through the real `cz` with every rule agreeing |
+| 5 | Wizard + wiring | `configure/commitizen/{detect,wizard}.py`, registry entry, README, CLAUDE.md, this spec | `devstuff configure commitizen` walks the steps, previews, checks, and saves with a backup |
+
+## Testing Strategy
+
+**`tests/test_configure_commitizen.py` — unit only, no `cz` required (NFR-5).** 114 tests:
+
+- **Model invariants:** every type key is regex-safe (it is spliced raw into four patterns);
+  shortcuts unique; bump levels known; `SAMPLE_BUMPS` is a real semver walk.
+- **Agreement with commitizen's shipped defaults:** the selected set, bump map and changelog set
+  are compared against constants transcribed from the installed package, and `CONFIG_FILES` is
+  compared against `commitizen.defaults.CONFIG_FILES` directly — the precedence warning is only
+  correct if that list is.
+- **TOML validity:** every convention × provider parses; regexes come back out of the parser
+  byte-identical (the literal-string guarantee); a quote in a user-supplied section name does not
+  produce an unparseable file.
+- **The generated rules, executed in Python:** `bump_pattern` group 1 is fed through `bump_map`
+  the way commitizen does it, and the result is asserted for `feat`, `feat(api)`, `docs`,
+  `feat(api)!`, `docs!`, and both spellings of the breaking footer. This is the offline half of
+  the FR-0 guarantee; the sandbox is the other half.
+- **Cross-consistency:** the bump table shown on screen is re-derived from the emitted map and
+  compared; `schema_pattern` is matched against messages produced by `message_template`; turning
+  off a question removes both the prompt and its template slot.
+- **Splicing:** append, replace, idempotency, other tables preserved, a similarly named table
+  (`[tool.commitizen_helper]`) not mistaken for ours, and the fail-closed case — a table header
+  inside a multi-line string returns `None` and the original file is untouched.
+- **Detection:** provider and version read off six project shapes; a `pyproject.toml` with no
+  commitizen section is not a config; a malformed file is not a config; JSON and YAML configs
+  recognised.
+- **Interactive steps:** the prompt helpers are driven through a scripted `ui` double, covering
+  the add-a-type validation paths, bump-level overrides, the empty-selection guard, the release
+  toggles, the commit hook (written executable; an existing one never touched) and the shadowing
+  warning.
+
+**`tests/integration/test_commitizen_config.py` — marked `integration`, needs `cz` and `git` but
+*not* sudo or the network** (unlike the rest of that directory — noted in its docstring). 12
+tests, ~24s. Seven configs (conventional, custom defaults, `major_version_zero`, pep440 with bare
+tags, no scope/body/footer, a two-type minimum, renamed sections with `docs` promoted to PATCH)
+are each replayed through `cz bump --dry-run`; plus a user-added type, the changelog headings,
+the exclusion of non-changelog types, a negative `cz check`, and `cz info` round-tripping the
+file through commitizen's own parser.
+
+**Manual verification.** The full wizard was driven end to end through a forked pty (the
+technique CLAUDE.md describes for the starship wizard) in a scratch git repo tagged `v0.3.0`:
+version and tag format were picked up from the tag, the review screen rendered, the automatic
+pre-save check reported "8 rules agree", and the written file was accepted by `cz --config …
+example`.
+
+## Risks
+
+| Risk | Mitigation |
+|------|-----------|
+| commitizen changes `find_increment`'s first-match-wins semantics, or how `bump_map` keys are matched | The integration suite replays real commits; a change shows up as a failed check rather than as wrong version numbers in the field. The wizard's pre-save check gives the same signal to users. |
+| commitizen changes its shipped defaults | `test_defaults_reproduce_commitizens_own_rules` and `test_config_file_order_matches_commitizens` compare against the installed package. |
+| The pyproject splice damages a user's file | The result is parsed back and compared to the intended settings; a mismatch aborts to `.cz.toml` and leaves the original untouched (FR-14). Every write is backed up first. |
+| `cz_customize` is renamed or removed upstream (commitizen's own docs warn of this — issue #1385) | The convention name lives in one place, `CONVENTIONS` in `model.py`. A rename is a one-line change plus a spec note. |
+| A user's own `commit-msg` hook is clobbered | The offer is only made when no hook exists (FR-18). |
+| The live check makes the wizard feel slow | It is an explicit action plus one automatic run at save (NFR-2), never on redraw. |
+
+## Follow-ups (not built)
+
+- Reading an existing config back into wizard state (SD-6 — deliberately out).
+- `pre_bump_hooks` / `post_bump_hooks` prompts (see the open questions in `specifications.md`).
+- Changelog template (`template`/`extras`) configuration.
+- A `.pre-commit-config.yaml` entry alongside the git hook (SD-9).
+- Configurators for anything other than starship and commitizen.

devstuff-1.18.0/docs/specs/commitizen-config/specifications.md

@@ -0,0 +1,119 @@
+# Specification: `devstuff configure commitizen`
+
+**Date:** 2026-07-31
+**Status:** Implemented (v1)
+**Authors:** Sawyer + Claude
+
+---
+
+## 1. Problem Statement & Goals
+
+`devstuff install commitizen` puts `cz` on the PATH. That is where it stops. Commitizen does
+nothing at all until a config file exists, and its `cz init` writes a five-key stub for
+`cz_conventional_commits` — which is fine right up to the moment somebody wants a type
+commitizen does not ship, or wants `docs:` to stop triggering releases, or wants their
+changelog headings to say something other than "Feat".
+
+Everything past that stub means `cz_customize`, and `cz_customize` is not a setting — it is
+nine coupled regexes and an ordered map. The user has to write a `bump_pattern` whose **group
+1** is what `bump_map`'s keys get `re.match`ed against, keep a `schema_pattern` in step with a
+Jinja2 `message_template` they also wrote, and put the two breaking-change rules at the *top*
+of `bump_map`, because commitizen stops at the first key that matches. Get the order wrong and
+`feat(api)!:` quietly ships as a minor release. Nothing tells you; the version is just wrong.
+
+`devstuff configure commitizen` replaces that with a wizard: choose the commit types, say what
+each one does to the version and where it lands in the changelog, and see the resulting bump
+table and changelog sections before anything is written — with the rules replayed through the
+real `cz` to confirm commitizen agrees.
+
+**Success criteria**
+- A user who has never read commitizen's config reference gets a working `cz_customize` setup,
+  with their own types and bump rules, in under two minutes.
+- The bump table the wizard shows is the bump commitizen actually performs — checked by
+  replaying commits through `cz bump --dry-run`, not asserted from intent.
+- Nothing is written until the user confirms; an existing config is never lost, and a
+  `pyproject.toml` is edited in place rather than rewritten.
+- The generated file is one a human can then hand-edit: commented, ordered, and using
+  commitizen's own key names rather than a devstuff-specific encoding.
+- Zero new runtime dependencies.
+
+**Non-goals**
+- A general-purpose config-wizard DSL declared in `tools.yaml` (SD-1, inherited from starship).
+- Round-tripping a hand-written config back into wizard state (SD-6).
+- `cz_jira` and third-party commitizen plugins (SD-8).
+- Writing JSON or YAML configs. commitizen reads `.cz.json`/`.cz.yaml`, but TOML is the form
+  every commitizen example is written in and the only one `pyproject.toml` can hold (SD-7).
+- Changelog *templates* (commitizen's `template`/`extras` Jinja2 hooks). Section names and
+  ordering are configurable here; the markdown around them is not.
+- Running `cz bump` for the user. The wizard configures releases; it does not cut one.
+
+## 2. Users & Personas
+
+| Persona | Description | Primary needs |
+|---------|-------------|---------------|
+| New commitizen user | Just ran `devstuff install commitizen` | A conventional-commits setup that works, without reading the manual |
+| Team lead | Wants house rules — a `deps:` type, `docs:` never releasing | Custom types and per-type bump levels, enforced on commit |
+| Polyglot maintainer | Rust/Node/PHP repo, not Python | A standalone config, the right version provider, semver not pep440 |
+| Existing user | Has a hand-written `[tool.commitizen]` | To not lose the rest of `pyproject.toml`, and to be told what is being replaced |
+
+## 3. Functional Requirements
+
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| FR-0 | Every generated config is loaded by the real `cz` without error, and produces exactly the increments the wizard's bump table claims, for every convention × provider × scheme × tag-format combination under test. | Must |
+| FR-1 | `commitizen` is a built-in catalog tool (`type: uvx`, `pip_name: commitizen`, `check_cmd: cz`, requires `uv`), so `devstuff install commitizen` works and `devstuff configure` offers the wizard afterwards. | Must |
+| FR-2 | The wizard covers: commit convention, which commit types exist, what each bumps, changelog membership and heading per type, version provider/scheme/tag format/version files, release toggles, the questions `cz commit` asks, and the destination file. | Must |
+| FR-3 | Two conventions — `cz_conventional_commits` (commitizen's own fixed rules, no `customize` block emitted) and `cz_customize` (everything configurable). | Must |
+| FR-4 | The built-in type table reproduces `commitizen.defaults.BUMP_MAP` and `ConventionalCommitsCz`'s picker exactly: the nine conventional types selected, `feat`→MINOR, `fix`/`refactor`/`perf`→PATCH, everything else no-release, and `feat`/`fix`/`refactor`/`perf` in the changelog. | Must |
+| FR-5 | Additional types (`chore`, `revert`, `deps`, `security`) are offered unselected; the user can also add their own with a key, description, bump level, changelog heading and hotkey. | Must |
+| FR-6 | The generated `bump_map` lists the two breaking-change rules (`^.+!$`, `^BREAKING[\-\ ]CHANGE`) first, since commitizen stops at the first matching key. | Must |
+| FR-7 | `bump_map_major_version_zero` is always emitted, derived from `bump_map` by demoting MAJOR to MINOR. | Must |
+| FR-8 | `schema_pattern` accepts every message `message_template` can produce, including the breaking form, and always accepts the `bump:` prefix commitizen's own release commit uses. | Must |
+| FR-9 | The review screen shows: a summary, a sample `cz commit` message, a bump table (`type → increment → resulting version` against 1.4.2), and the changelog sections with the types filed under each. | Must |
+| FR-10 | "Check these rules against the real cz" builds a throwaway git repo tagged at 1.4.2, replays one commit per distinct bump level plus both breaking forms through `cz bump --dry-run`, and reports agreement or disagreement per rule. | Must |
+| FR-11 | The same check runs automatically before saving. A disagreement is reported and requires confirmation, but never blocks the save — the user's config is the user's. | Must |
+| FR-12 | "Preview a generated changelog" runs the real `cz changelog --dry-run` over one sample commit per selected type. | Should |
+| FR-13 | The wizard detects, and defaults from: git root, existing commitizen configs (in commitizen's own search order, skipping files without a commitizen section), version provider and current version from project files, latest git tag, and an existing changelog file. | Must |
+| FR-14 | Writing to `pyproject.toml` replaces every `[tool.commitizen…]` table and leaves the rest of the file byte for byte. The result is verified by parsing it back; if it does not match, the write falls back to a standalone `.cz.toml` and the original file is untouched. | Must |
+| FR-15 | Any file about to be overwritten is copied to `<name>.bak.<timestamp>` first. A config not written by this wizard prompts before being replaced. | Must |
+| FR-16 | Nothing is written until the user picks "Save"; "Cancel" writes nothing. | Must |
+| FR-17 | After saving, if more than one commitizen config now exists in the project, the wizard names them and says which one commitizen will actually read. | Must |
+| FR-18 | After saving into a git repo with no `commit-msg` hook, the wizard offers to install one running `cz check --allow-abort --commit-msg-file "$1"`. An existing hook is never replaced. | Should |
+| FR-19 | `devstuff configure commitizen --path` prints the config file commitizen would read here, or where the wizard would create one. | Must |
+| FR-20 | `devstuff configure commitizen --output PATH` writes a standalone config to `PATH` and touches nothing in the project — no destination question, no shadowing warning, no git hook. | Must |
+| FR-21 | Without `cz` installed, the wizard still runs end to end; the live checks say so rather than failing. | Must |
+| FR-22 | Two selected types sharing a hotkey is reported — commitizen does not validate it, and the second type simply becomes unreachable. | Should |
+| FR-23 | Deselecting every type keeps the previous selection: an empty alternation would match everything. | Must |
+
+## 4. Non-Functional Requirements
+
+| ID | Requirement |
+|----|-------------|
+| NFR-1 | No new runtime dependencies. TOML is emitted as text and read back with stdlib `tomllib`. |
+| NFR-2 | A live check completes in a few seconds (~8 `cz` invocations); it is an explicit menu action plus one automatic run at save time, never on every redraw. |
+| NFR-3 | Every live-check failure path degrades to the offline table. A check must never be able to end the wizard. |
+| NFR-4 | The generated file is stable: the same answers produce the same bytes, and re-splicing an already-spliced `pyproject.toml` is a no-op. |
+| NFR-5 | Unit tests run without `cz` installed. The commitizen-backed tests are marked `integration`. |
+
+## 5. Verification
+
+| Requirement | How it is verified |
+|-------------|--------------------|
+| FR-0, FR-10 | `tests/integration/test_commitizen_config.py` — seven configs replayed through the real `cz` |
+| FR-4 | `test_defaults_reproduce_commitizens_own_rules`, against constants read out of the installed package |
+| FR-6, FR-7 | `test_bump_map_leads_with_the_breaking_rules`, `test_major_version_zero_demotes_only_the_breaking_rules` |
+| FR-8 | `test_schema_pattern_accepts_the_wizards_own_messages`, `test_schema_pattern_always_accepts_commitizens_own_bump_commit` |
+| FR-13 | `test_the_version_provider_is_read_off_the_project`, `test_existing_configs_follow_commitizens_search_order` |
+| FR-14 | `test_splice_*` — including the fail-closed case and idempotency |
+| FR-15, FR-18 | `test_save_backs_up_what_was_there`, `test_an_existing_commit_hook_is_never_touched` |
+| FR-17 | `test_shadowing_another_config_is_called_out` |
+| FR-22, FR-23 | `test_duplicate_shortcuts_are_reported`, `test_deselecting_everything_keeps_the_previous_types` |
+
+## 6. Open Questions
+
+| Question | Status |
+|----------|--------|
+| Should the wizard read an existing config back into its state? | **Resolved 2026-07-31 — no.** See SD-6: partial reconstruction is worse than none, and the timestamped backup covers the real need. |
+| Should a disagreement from the live check block saving? | **Resolved 2026-07-31 — no.** FR-11: it warns and asks. A check that can veto a save turns a helpful cross-check into an obstacle the moment commitizen changes. |
+| Should `pre_bump_hooks`/`post_bump_hooks` be configurable? | **Deferred.** They are shell commands with eight environment variables; a text prompt for them would be a worse editor than `$EDITOR`. Hand-editable in the generated file. |
+| Should the wizard offer a `.pre-commit-config.yaml` entry as well as a git hook? | **Deferred.** It means owning a second file's merge semantics; the git hook covers the same need with no new file format. |