From cd2cf5c75b23bd19a3b5f2e9b38338863796934f Mon Sep 17 00:00:00 2001 From: Gaven Lan Ren Date: Wed, 28 Oct 2026 10:51:14 -0400 Subject: [PATCH 1/5] docs(git): clarify auto-commit default fallback Explain that auto_commit.default only applies to events without a section, and that the shipped explicit disabled entries require enabled: true. Document removal of the whole event section to restore fallback behavior. Validation: existing Bash/Python auto-commit parity suite: 11 passed, 1 skipped (root cannot model unreadable files); git diff --check passed. Fixes github/spec-kit#5050 Assisted-by: OpenAI Codex (model: unknown, autonomous) --- extensions/git/README.md | 7 +++++++ extensions/git/config-template.yml | 5 +++-- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/extensions/git/README.md b/extensions/git/README.md index c0cb7b5d00..4706d8cbfa 100644 --- a/extensions/git/README.md +++ b/extensions/git/README.md @@ -80,6 +80,13 @@ auto_commit: message: "[Spec Kit] Add specification" ``` +`auto_commit.default` applies only to events without an event section. The +installed config template lists each event with `enabled: false`, so changing +only `default` to `true` does not enable those events. Set `enabled: true` for +each listed event you want to enable, as shown for `after_specify` above. To use +the default for an event, remove its entire section; removing only `enabled` +while leaving `message` does not enable the fallback. + `{author}` is derived from Git config and sanitized for branch names. `{app}` is derived from the Spec Kit init directory name. Custom templates must not put `{slug}` before `{number}`, and must put `{number}-` at the start of the final path segment so generated names remain valid feature branches. For a monorepo project at `apps/web/.specify/`, a template such as `{author}/{app}/{number}-{slug}` produces branches like `jdoe/web/008-guided-tour`. For simple namespace-only customization, `branch_prefix` is also accepted as a shorthand and expands to `/{number}-{slug}`. diff --git a/extensions/git/config-template.yml b/extensions/git/config-template.yml index 2ea3471742..c192469ce2 100644 --- a/extensions/git/config-template.yml +++ b/extensions/git/config-template.yml @@ -25,8 +25,9 @@ init_commit_message: "[Spec Kit] Initial commit" commit_style: fixed # Auto-commit before/after core commands. -# Set "default" to enable for all commands, then override per-command. -# Each key can be true/false. Message is customizable per-command. +# "default" applies only to events that have no section below. +# Listed events must use "enabled: true" to opt in, even if default is true. +# Messages are customizable per event. auto_commit: default: false before_clarify: From 5af37689da953ae1361e562f4f3381b1267a7518 Mon Sep 17 00:00:00 2001 From: Gaven Lan Ren Date: Wed, 28 Oct 2026 11:16:32 -0400 Subject: [PATCH 2/5] docs(git): align shipped auto-commit guidance Address PR #5158 review by correcting the actual copied git-config.yml and the commit command's configuration example and fallback instructions. Validation: existing auto-commit parity checks: 11 passed, 1 skipped. No executable code or configuration values changed. Assisted-by: OpenAI Codex (model: unknown, autonomous) --- extensions/git/commands/speckit.git.commit.md | 8 ++++++-- extensions/git/git-config.yml | 5 +++-- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/extensions/git/commands/speckit.git.commit.md b/extensions/git/commands/speckit.git.commit.md index 3270eb27c6..8328328820 100644 --- a/extensions/git/commands/speckit.git.commit.md +++ b/extensions/git/commands/speckit.git.commit.md @@ -13,7 +13,7 @@ This command is invoked as a hook after (or before) core commands. It: 1. Determines the event name from the hook context (e.g., if invoked as an `after_specify` hook, the event is `after_specify`; if `before_plan`, the event is `before_plan`) 2. Checks `.specify/extensions/git/git-config.yml` for the `auto_commit` section 3. Looks up the specific event key to see if auto-commit is enabled -4. Falls back to `auto_commit.default` if no event-specific key exists +4. Falls back to `auto_commit.default` if no section exists for the event 5. Determines the commit message based on `commit_style` (see below) 6. If enabled and there are uncommitted changes, runs `git add .` + `git commit` @@ -46,7 +46,7 @@ In `.specify/extensions/git/git-config.yml`: commit_style: fixed auto_commit: - default: false # Global toggle — set true to enable for all commands + default: false # Fallback for events without a section after_specify: enabled: true # Override per-command message: "[Spec Kit] Add specification" @@ -55,6 +55,10 @@ auto_commit: message: "[Spec Kit] Add implementation plan" ``` +Listed events need `enabled: true` to opt in, even when `default` is `true`. +Remove an event's entire section to use the default; leaving its `message` +entry still prevents fallback. + ## Graceful Degradation - If Git is not available or the current directory is not a repository: skips with a warning diff --git a/extensions/git/git-config.yml b/extensions/git/git-config.yml index 2ea3471742..c192469ce2 100644 --- a/extensions/git/git-config.yml +++ b/extensions/git/git-config.yml @@ -25,8 +25,9 @@ init_commit_message: "[Spec Kit] Initial commit" commit_style: fixed # Auto-commit before/after core commands. -# Set "default" to enable for all commands, then override per-command. -# Each key can be true/false. Message is customizable per-command. +# "default" applies only to events that have no section below. +# Listed events must use "enabled: true" to opt in, even if default is true. +# Messages are customizable per event. auto_commit: default: false before_clarify: From 3f3db7f0867ae94e019b3c9c4ef80330a914e96a Mon Sep 17 00:00:00 2001 From: Gaven Lan Ren Date: Wed, 28 Oct 2026 13:29:55 -0400 Subject: [PATCH 3/5] docs(git): keep boolean comments on separate lines The auto-commit example is copied into `git-config.yml`, whose lightweight parsers include inline comments in boolean values. Move the two comments above their keys so listed enable and unlisted-event fallback examples work without changing their values. Validation: extract the actual fenced example and run both Bash and Python scripts in real temporary Git projects. Four cases per runtime now pass; four positive results failed before. Existing parity tests: 11 passed, 1 root-permission skip. No PowerShell execution is claimed. Assisted-by: OpenAI Codex (model: unknown, autonomous) --- extensions/git/commands/speckit.git.commit.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/extensions/git/commands/speckit.git.commit.md b/extensions/git/commands/speckit.git.commit.md index 8328328820..47c0f541f4 100644 --- a/extensions/git/commands/speckit.git.commit.md +++ b/extensions/git/commands/speckit.git.commit.md @@ -46,9 +46,11 @@ In `.specify/extensions/git/git-config.yml`: commit_style: fixed auto_commit: - default: false # Fallback for events without a section + # Fallback for events without a section + default: false after_specify: - enabled: true # Override per-command + # Override per-command + enabled: true message: "[Spec Kit] Add specification" after_plan: enabled: false From 9ccb7833f526d02345294e888ae6fcd07c70614b Mon Sep 17 00:00:00 2001 From: Gaven Lan Ren Date: Wed, 28 Oct 2026 14:27:21 -0400 Subject: [PATCH 4/5] docs: explain fallback commit messages and bump git extension Clarify that removing an event section in fixed-message mode also removes its custom message. Show the resulting after_specify fallback message and recommend enabled:true when retaining a custom message. Increase the bundled git extension and catalog versions together from 1.0.1 to 1.0.2 so the revised installed instructions reach existing installations and satisfy the extension version guard. Auto-commit parity and version-contract checks pass (49 passed, one root-permission skip). Six real Bash/Python Git checks confirm custom, fallback, and explicitly disabled cases. No executable script or PowerShell behavior changes. Assisted-by: OpenAI Codex (model: unknown, autonomous) --- extensions/catalog.json | 2 +- extensions/git/README.md | 5 +++++ extensions/git/commands/speckit.git.commit.md | 3 +++ extensions/git/config-template.yml | 2 ++ extensions/git/extension.yml | 2 +- extensions/git/git-config.yml | 2 ++ 6 files changed, 14 insertions(+), 2 deletions(-) diff --git a/extensions/catalog.json b/extensions/catalog.json index c20cec03e6..cfd475d973 100644 --- a/extensions/catalog.json +++ b/extensions/catalog.json @@ -51,7 +51,7 @@ "git": { "name": "Git Branching Workflow", "id": "git", - "version": "1.0.1", + "version": "1.0.2", "description": "Feature branch creation, numbering (sequential/timestamp), validation, and Git remote detection", "author": "spec-kit-core", "repository": "https://github.com/github/spec-kit", diff --git a/extensions/git/README.md b/extensions/git/README.md index 4706d8cbfa..b896198621 100644 --- a/extensions/git/README.md +++ b/extensions/git/README.md @@ -87,6 +87,11 @@ each listed event you want to enable, as shown for `after_specify` above. To use the default for an event, remove its entire section; removing only `enabled` while leaving `message` does not enable the fallback. +With `commit_style: fixed`, removing the section also removes its custom +message. A fallback commit uses `[Spec Kit] Auto-commit after specify` for +`after_specify` (and the corresponding phase and command for other events). +Keep the section and set `enabled: true` to retain its custom message. + `{author}` is derived from Git config and sanitized for branch names. `{app}` is derived from the Spec Kit init directory name. Custom templates must not put `{slug}` before `{number}`, and must put `{number}-` at the start of the final path segment so generated names remain valid feature branches. For a monorepo project at `apps/web/.specify/`, a template such as `{author}/{app}/{number}-{slug}` produces branches like `jdoe/web/008-guided-tour`. For simple namespace-only customization, `branch_prefix` is also accepted as a shorthand and expands to `/{number}-{slug}`. diff --git a/extensions/git/commands/speckit.git.commit.md b/extensions/git/commands/speckit.git.commit.md index 47c0f541f4..3a230e41e3 100644 --- a/extensions/git/commands/speckit.git.commit.md +++ b/extensions/git/commands/speckit.git.commit.md @@ -60,6 +60,9 @@ auto_commit: Listed events need `enabled: true` to opt in, even when `default` is `true`. Remove an event's entire section to use the default; leaving its `message` entry still prevents fallback. +With `commit_style: fixed`, removing the section also drops its custom message: +`after_specify` then uses `[Spec Kit] Auto-commit after specify`. Keep the +section with `enabled: true` to retain its configured message. ## Graceful Degradation diff --git a/extensions/git/config-template.yml b/extensions/git/config-template.yml index c192469ce2..63d995a534 100644 --- a/extensions/git/config-template.yml +++ b/extensions/git/config-template.yml @@ -28,6 +28,8 @@ commit_style: fixed # "default" applies only to events that have no section below. # Listed events must use "enabled: true" to opt in, even if default is true. # Messages are customizable per event. +# In fixed mode, removing an event section also removes its custom message; +# keep the section with "enabled: true" to retain that message. auto_commit: default: false before_clarify: diff --git a/extensions/git/extension.yml b/extensions/git/extension.yml index 90a7e56769..2d762a126a 100644 --- a/extensions/git/extension.yml +++ b/extensions/git/extension.yml @@ -3,7 +3,7 @@ schema_version: "1.0" extension: id: git name: "Git Branching Workflow" - version: "1.0.1" + version: "1.0.2" description: "Feature branch creation, numbering (sequential/timestamp), templating, validation, and Git remote detection" author: spec-kit-core repository: https://github.com/github/spec-kit diff --git a/extensions/git/git-config.yml b/extensions/git/git-config.yml index c192469ce2..63d995a534 100644 --- a/extensions/git/git-config.yml +++ b/extensions/git/git-config.yml @@ -28,6 +28,8 @@ commit_style: fixed # "default" applies only to events that have no section below. # Listed events must use "enabled: true" to opt in, even if default is true. # Messages are customizable per event. +# In fixed mode, removing an event section also removes its custom message; +# keep the section with "enabled: true" to retain that message. auto_commit: default: false before_clarify: From 7ef05ca63bc63cf6580e50fbcc8d9df950151092 Mon Sep 17 00:00:00 2001 From: Gaven Lan Ren Date: Wed, 28 Oct 2026 14:53:55 -0400 Subject: [PATCH 5/5] test: match the bundled git extension version Update the manifest validation assertion to 1.0.2 alongside the Git extension's required manifest/catalog version bump. The old assertion fails against the bumped manifest. The complete Git extension test directory plus bundled-version and version-guard contracts now pass: 163 passed, 51 skipped. No Windows or PowerShell execution is claimed. Assisted-by: OpenAI Codex (model: unknown, autonomous) --- tests/extensions/git/test_git_extension.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/extensions/git/test_git_extension.py b/tests/extensions/git/test_git_extension.py index 1760e496d1..4915544dbc 100644 --- a/tests/extensions/git/test_git_extension.py +++ b/tests/extensions/git/test_git_extension.py @@ -145,7 +145,7 @@ def test_manifest_validates(self): m = ExtensionManifest(EXT_DIR / "extension.yml") assert m.id == "git" - assert m.version == "1.0.1" + assert m.version == "1.0.2" def test_manifest_commands(self): """Manifest declares expected commands."""