docs(git): clarify auto-commit default fallback

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",

extensions/git/README.md

@@ -80,6 +80,18 @@ 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.
+
+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 `<branch_prefix>/{number}-{slug}`.

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,15 +46,24 @@ In `.specify/extensions/git/git-config.yml`:
 commit_style: fixed
 
 auto_commit:
-  default: false          # Global toggle — set true to enable for all commands
+  # 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
     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.
+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
 
 - If Git is not available or the current directory is not a repository: skips with a warning

extensions/git/config-template.yml

@@ -25,8 +25,11 @@ 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.
+# 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:

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

extensions/git/git-config.yml

@@ -25,8 +25,11 @@ 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.
+# 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:

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."""