@sienklogic/plan-build-run 2.56.2 → 2.56.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.56.2",
+  "version": "2.56.3",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",

package/plugins/codex-pbr/AGENTS.md

@@ -177,14 +177,14 @@ When executing a plan:
 **Commit message format:**
 
 ```
-{type}({phase}-{plan}): {description}
+{type}({scope}): {description}
 ```
 
 Examples:
-- `feat(01-01): implement configuration loader`
-- `fix(01-01): handle missing DB_PORT with default value`
-- `test(01-01): add unit tests for config validation`
-- `refactor(02-01): extract auth middleware into separate module`
+- `feat(config): implement configuration loader`
+- `fix(config): handle missing DB_PORT with default value`
+- `test(config): add unit tests for config validation`
+- `refactor(auth): extract auth middleware into separate module`
 
 Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
 
@@ -196,8 +196,8 @@ phase: "01-setup"
 plan: "01-01"
 status: "complete"
 commits:
-  - "abc1234: feat(01-01): implement configuration loader"
-  - "def5678: feat(01-01): create database connection module"
+  - "abc1234: feat(config): implement configuration loader"
+  - "def5678: feat(database): create database connection module"
 key_files:
   - "src/config.ts"
   - "src/database.ts"
@@ -291,7 +291,7 @@ Before any `git commit`, verify the message matches:
 ```
 
 - **Valid types**: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
-- **Valid scopes**: `NN-MM` (phase-plan), `quick-NNN`, `planning`, or a descriptive word
+- **Valid scopes**: a short descriptive word for what changed (e.g., `auth`, `config`, `executor`), `quick-NNN`, `planning`
 - **Block the commit** if the format doesn't match — fix the message first
 
 ### Gate 2: Plan-Before-Build

package/plugins/codex-pbr/agents/executor.md

@@ -100,7 +100,7 @@ One task = one commit. Exception: TDD tasks get 3 commits (RED, GREEN, REFACTOR)
 ### Commit Format
 
 ```
-{type}({phase}-{plan}): {description}
+{type}({scope}): {description}
 ```
 
 | Type | When |
@@ -119,7 +119,7 @@ Stage only files listed in the task's `<files>`. If git commit fails with lock e
 When the plan frontmatter contains a non-empty `closes_issues` array, append issue-closing syntax to the **final** commit body for the plan:
 
 ```
-git commit -m "feat(01-02): implement user auth
+git commit -m "feat(auth): implement user auth
 
 Closes #42
 Closes #57"
@@ -217,9 +217,9 @@ When a task has `tdd="true"`, follow Red-Green-Refactor:
 
 | Phase | Action | Test Must | Commit | If Wrong |
 |-------|--------|-----------|--------|----------|
-| RED | Write test from `<done>` | FAIL | `test(NN-MM): RED - ...` | Passes? Fix test. |
-| GREEN | Minimal code to pass | PASS | `feat(NN-MM): GREEN - ...` | Fails? Fix code. |
-| REFACTOR | Clean up, keep behavior | PASS | `refactor(NN-MM): REFACTOR - ...` | Breaks? Revert. |
+| RED | Write test from `<done>` | FAIL | `test({scope}): RED - ...` | Passes? Fix test. |
+| GREEN | Minimal code to pass | PASS | `refactor({scope}): GREEN - ...` | Fails? Fix code. |
+| REFACTOR | Clean up, keep behavior | PASS | `refactor({scope}): REFACTOR - ...` | Breaks? Revert. |
 
 ---
 

package/plugins/codex-pbr/agents/general.md

@@ -50,7 +50,7 @@ This agent is available for ad-hoc `Task()` calls from skills or custom orchestr
 
 All commits follow: `{type}({scope}): {description}`
 - **Types**: feat, fix, refactor, test, docs, chore, wip
-- **Scopes**: `{phase}-{plan}` (e.g., `03-01`), `quick-{NNN}`, `planning`
+- **Scopes**: descriptive word (e.g., `auth`, `api`, `executor`), `quick-{NNN}`, `planning`
 
 ## Self-Escalation
 

package/plugins/codex-pbr/references/config-reference.md

@@ -151,7 +151,7 @@ Controls git integration and branching strategy.
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `branching` | string | `none` | Branching strategy: `none`, `phase`, `milestone`, `disabled` |
-| `commit_format` | string | `{type}({phase}-{plan}): {description}` | Commit message template |
+| `commit_format` | string | `{type}({scope}): {description}` | Commit message template. Use a short descriptive word as the scope (e.g., `auth`, `config`, `executor`) rather than phase-plan numbers. |
 | `phase_branch_template` | string | `plan-build-run/phase-{phase}-{slug}` | Phase branch name pattern |
 | `milestone_branch_template` | string | `plan-build-run/{milestone}-{slug}` | Milestone branch name pattern |
 | `mode` | string | `enabled` | Git mode: `enabled` or `disabled` |

package/plugins/codex-pbr/references/git-integration.md

@@ -7,23 +7,22 @@ Plan-Build-Run's commit conventions, commit points, branching strategy, and hook
 ## Commit Message Format
 
 ```
-{type}({phase}-{plan}): {description}
+{type}({scope}): {description}
 ```
 
 ### Components
 
 | Part | Description | Example |
 |------|-------------|---------|
-| `{type}` | Conventional commit type | `feat`, `fix`, `test` |
-| `{phase}` | Phase number (zero-padded) | `02` |
-| `{plan}` | Plan number | `01` |
-| `{description}` | Imperative, lowercase description | `implement discord oauth client` |
+| `{type}` | Conventional commit type | `feat`, `fix`, `chore` |
+| `{scope}` | Descriptive word for the area of change | `auth`, `executor`, `changelog` |
+| `{description}` | Imperative, lowercase description | `add discord oauth flow` |
 
-The format is configurable via `config.json` at `git.commit_format`. The default is `{type}({phase}-{plan}): {description}`.
+The format is configurable via `config.json` at `git.commit_format`. The default is `{type}({scope}): {description}`.
 
 ### Full Example
 ```
-feat(02-01): implement discord oauth client
+feat(auth): implement discord oauth client
 ```
 
 ---
@@ -32,19 +31,35 @@ feat(02-01): implement discord oauth client
 
 | Type | When to Use | Example |
 |------|------------|---------|
-| `feat` | New feature or functionality | `feat(02-01): implement discord oauth client` |
-| `fix` | Bug fix (including during execution) | `fix(02-01): handle null user profile from discord api` |
-| `refactor` | Code restructuring, no behavior change | `refactor(02-01): extract token validation into helper` |
-| `test` | Adding or modifying tests | `test(02-01): add failing tests for discord oauth flow` |
-| `docs` | Documentation changes | `docs(03-02): add api endpoint documentation` |
-| `chore` | Build config, dependencies, tooling | `chore(01-01): configure typescript and eslint` |
-| `style` | Formatting, whitespace (no logic change) | `style(02-01): fix import ordering` |
+| `feat` | New feature or functionality | `feat(auth): implement discord oauth client` |
+| `fix` | Bug fix (including during execution) | `fix(api): handle null user profile from discord` |
+| `refactor` | Code restructuring, no behavior change | `refactor(auth): extract token validation into helper` |
+| `test` | Adding or modifying tests | `test(auth): add failing tests for oauth flow` |
+| `docs` | Documentation changes | `docs(planning): add api endpoint documentation` |
+| `chore` | Build config, dependencies, tooling | `chore(deps): configure typescript and eslint` |
+| `style` | Formatting, whitespace (no logic change) | `style(auth): fix import ordering` |
+
+---
+
+## Commit Type Discipline
+
+| Type | Use For | Appears in Changelog |
+|------|---------|---------------------|
+| `feat` | User-visible features ONLY (new commands, new config options, changed behavior users notice) | YES |
+| `fix` | Bug fixes users would notice | YES |
+| `refactor` | Internal restructuring, TDD GREEN commits, code cleanup | No |
+| `test` | Test additions including TDD RED commits | No |
+| `docs` | Documentation (hidden — mostly planning artifacts) | No |
+| `chore` | Build config, deps, tooling, internal scaffolding | No |
+| `wip` | Work in progress (use sparingly) | No |
+
+**TDD commits**: RED phase → `test({scope}): RED - ...`, GREEN phase → `refactor({scope}): GREEN - ...`, REFACTOR phase → `refactor({scope}): REFACTOR - ...`
 
 ---
 
 ## Special Commit Scopes
 
-Beyond the standard `{phase}-{plan}` scope, Plan-Build-Run recognizes these additional patterns:
+Beyond descriptive scopes, Plan-Build-Run recognizes these additional patterns:
 
 | Pattern | When Used | Example |
 |---------|-----------|---------|
@@ -84,9 +99,9 @@ Each successfully completed plan task gets exactly one atomic commit. No more, n
 TDD tasks (`tdd="true"`) produce exactly 3 commits following Red-Green-Refactor:
 
 ```
-test(02-01): RED - add failing tests for auth middleware
-feat(02-01): GREEN - implement auth middleware to pass tests
-refactor(02-01): REFACTOR - extract token verification helper
+test(auth): RED - add failing tests for auth middleware
+refactor(auth): GREEN - implement auth middleware to pass tests
+refactor(auth): REFACTOR - extract token verification helper
 ```
 
 ### Commit Preconditions
@@ -125,15 +140,15 @@ When an executor applies a deviation rule during a task, the deviation is includ
 ```bash
 # Standard task
 git add src/auth/discord.ts src/auth/types.ts
-git commit -m "feat(02-01): implement Discord OAuth client with token exchange"
+git commit -m "feat(auth): implement Discord OAuth client with token exchange"
 
 # Task that also installed a dependency (Rule 2)
 git add src/auth/discord.ts src/auth/types.ts package.json package-lock.json
-git commit -m "feat(02-01): implement Discord OAuth client with token exchange"
+git commit -m "feat(auth): implement Discord OAuth client with token exchange"
 
 # TDD RED
 git add tests/auth/discord.test.ts
-git commit -m "test(02-01): add failing tests for Discord OAuth flow"
+git commit -m "test(auth): add failing tests for Discord OAuth flow"
 ```
 
 ---

package/plugins/codex-pbr/skills/undo/SKILL.md

@@ -63,9 +63,9 @@ Present grouped output:
 ```
 Recent PBR commits (grouped by scope):
 
-[55-02] Phase 55, Plan 02
-  abc1234  feat(55-02): add undo skill
-  def5678  chore(55-02): register undo command
+[undo]
+  abc1234  feat(undo): add undo skill
+  def5678  chore(undo): register undo command
 
 [quick-003]
   ghi9012  fix(quick-003): fix hook path resolution
@@ -74,7 +74,7 @@ Recent PBR commits (grouped by scope):
   jkl3456  docs(planning): update roadmap phase 55
 ```
 
-For phase-plan scopes (NN-MM pattern), add a "Phase NN, Plan MM" annotation. For other scopes, show just the scope label.
+For descriptive scopes, show just the scope label. For phase-plan scopes (NN-MM pattern, from older commits), add a "Phase NN, Plan MM" annotation.
 
 ---
 
@@ -102,8 +102,8 @@ Display the commits that will be reverted:
 ```
 The following commits will be reverted (using git revert, NOT git reset):
 
-  abc1234  feat(55-02): add undo skill
-  def5678  chore(55-02): register undo command
+  abc1234  feat(undo): add undo skill
+  def5678  chore(undo): register undo command
 
 This creates new revert commits — your history is preserved.
 ```
@@ -125,7 +125,7 @@ git revert --no-commit {hash}
 ```
 
 After all reverts are staged, determine the commit message:
-- Extract scope from the first commit being reverted (e.g., `55-02`)
+- Extract scope from the first commit being reverted (e.g., `undo`, `auth`, `executor`)
 - If reverting a **single commit**: `revert({scope}): undo {original description}`
 - If reverting **multiple commits**: `revert({scope}): undo {N} commits from {scope}`
 

package/plugins/copilot-pbr/agents/executor.agent.md

@@ -100,7 +100,7 @@ One task = one commit. Exception: TDD tasks get 3 commits (RED, GREEN, REFACTOR)
 ### Commit Format
 
 ```
-{type}({phase}-{plan}): {description}
+{type}({scope}): {description}
 ```
 
 | Type | When |
@@ -119,7 +119,7 @@ Stage only files listed in the task's `<files>`. If git commit fails with lock e
 When the plan frontmatter contains a non-empty `closes_issues` array, append issue-closing syntax to the **final** commit body for the plan:
 
 ```
-git commit -m "feat(01-02): implement user auth
+git commit -m "feat(auth): implement user auth
 
 Closes #42
 Closes #57"
@@ -217,9 +217,9 @@ When a task has `tdd="true"`, follow Red-Green-Refactor:
 
 | Phase | Action | Test Must | Commit | If Wrong |
 |-------|--------|-----------|--------|----------|
-| RED | Write test from `<done>` | FAIL | `test(NN-MM): RED - ...` | Passes? Fix test. |
-| GREEN | Minimal code to pass | PASS | `feat(NN-MM): GREEN - ...` | Fails? Fix code. |
-| REFACTOR | Clean up, keep behavior | PASS | `refactor(NN-MM): REFACTOR - ...` | Breaks? Revert. |
+| RED | Write test from `<done>` | FAIL | `test({scope}): RED - ...` | Passes? Fix test. |
+| GREEN | Minimal code to pass | PASS | `refactor({scope}): GREEN - ...` | Fails? Fix code. |
+| REFACTOR | Clean up, keep behavior | PASS | `refactor({scope}): REFACTOR - ...` | Breaks? Revert. |
 
 ---
 

package/plugins/copilot-pbr/agents/general.agent.md

@@ -50,7 +50,7 @@ This agent is available for ad-hoc `Task()` calls from skills or custom orchestr
 
 All commits follow: `{type}({scope}): {description}`
 - **Types**: feat, fix, refactor, test, docs, chore, wip
-- **Scopes**: `{phase}-{plan}` (e.g., `03-01`), `quick-{NNN}`, `planning`
+- **Scopes**: descriptive word (e.g., `auth`, `api`, `executor`), `quick-{NNN}`, `planning`
 
 ## Self-Escalation
 

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.56.2",
+  "version": "2.56.3",
   "description": "Plan-Build-Run — Structured development workflow for GitHub Copilot CLI. Solves context rot through disciplined agent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/copilot-pbr/references/config-reference.md

@@ -151,7 +151,7 @@ Controls git integration and branching strategy.
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `branching` | string | `none` | Branching strategy: `none`, `phase`, `milestone`, `disabled` |
-| `commit_format` | string | `{type}({phase}-{plan}): {description}` | Commit message template |
+| `commit_format` | string | `{type}({scope}): {description}` | Commit message template. Use a short descriptive word as the scope (e.g., `auth`, `config`, `executor`) rather than phase-plan numbers. |
 | `phase_branch_template` | string | `plan-build-run/phase-{phase}-{slug}` | Phase branch name pattern |
 | `milestone_branch_template` | string | `plan-build-run/{milestone}-{slug}` | Milestone branch name pattern |
 | `mode` | string | `enabled` | Git mode: `enabled` or `disabled` |

package/plugins/copilot-pbr/references/git-integration.md

@@ -7,23 +7,22 @@ Plan-Build-Run's commit conventions, commit points, branching strategy, and hook
 ## Commit Message Format
 
 ```
-{type}({phase}-{plan}): {description}
+{type}({scope}): {description}
 ```
 
 ### Components
 
 | Part | Description | Example |
 |------|-------------|---------|
-| `{type}` | Conventional commit type | `feat`, `fix`, `test` |
-| `{phase}` | Phase number (zero-padded) | `02` |
-| `{plan}` | Plan number | `01` |
-| `{description}` | Imperative, lowercase description | `implement discord oauth client` |
+| `{type}` | Conventional commit type | `feat`, `fix`, `chore` |
+| `{scope}` | Descriptive word for the area of change | `auth`, `executor`, `changelog` |
+| `{description}` | Imperative, lowercase description | `add discord oauth flow` |
 
-The format is configurable via `config.json` at `git.commit_format`. The default is `{type}({phase}-{plan}): {description}`.
+The format is configurable via `config.json` at `git.commit_format`. The default is `{type}({scope}): {description}`.
 
 ### Full Example
 ```
-feat(02-01): implement discord oauth client
+feat(auth): implement discord oauth client
 ```
 
 ---
@@ -32,19 +31,35 @@ feat(02-01): implement discord oauth client
 
 | Type | When to Use | Example |
 |------|------------|---------|
-| `feat` | New feature or functionality | `feat(02-01): implement discord oauth client` |
-| `fix` | Bug fix (including during execution) | `fix(02-01): handle null user profile from discord api` |
-| `refactor` | Code restructuring, no behavior change | `refactor(02-01): extract token validation into helper` |
-| `test` | Adding or modifying tests | `test(02-01): add failing tests for discord oauth flow` |
-| `docs` | Documentation changes | `docs(03-02): add api endpoint documentation` |
-| `chore` | Build config, dependencies, tooling | `chore(01-01): configure typescript and eslint` |
-| `style` | Formatting, whitespace (no logic change) | `style(02-01): fix import ordering` |
+| `feat` | New feature or functionality | `feat(auth): implement discord oauth client` |
+| `fix` | Bug fix (including during execution) | `fix(api): handle null user profile from discord` |
+| `refactor` | Code restructuring, no behavior change | `refactor(auth): extract token validation into helper` |
+| `test` | Adding or modifying tests | `test(auth): add failing tests for oauth flow` |
+| `docs` | Documentation changes | `docs(planning): add api endpoint documentation` |
+| `chore` | Build config, dependencies, tooling | `chore(deps): configure typescript and eslint` |
+| `style` | Formatting, whitespace (no logic change) | `style(auth): fix import ordering` |
+
+---
+
+## Commit Type Discipline
+
+| Type | Use For | Appears in Changelog |
+|------|---------|---------------------|
+| `feat` | User-visible features ONLY (new commands, new config options, changed behavior users notice) | YES |
+| `fix` | Bug fixes users would notice | YES |
+| `refactor` | Internal restructuring, TDD GREEN commits, code cleanup | No |
+| `test` | Test additions including TDD RED commits | No |
+| `docs` | Documentation (hidden — mostly planning artifacts) | No |
+| `chore` | Build config, deps, tooling, internal scaffolding | No |
+| `wip` | Work in progress (use sparingly) | No |
+
+**TDD commits**: RED phase → `test({scope}): RED - ...`, GREEN phase → `refactor({scope}): GREEN - ...`, REFACTOR phase → `refactor({scope}): REFACTOR - ...`
 
 ---
 
 ## Special Commit Scopes
 
-Beyond the standard `{phase}-{plan}` scope, Plan-Build-Run recognizes these additional patterns:
+Beyond descriptive scopes, Plan-Build-Run recognizes these additional patterns:
 
 | Pattern | When Used | Example |
 |---------|-----------|---------|
@@ -84,9 +99,9 @@ Each successfully completed plan task gets exactly one atomic commit. No more, n
 TDD tasks (`tdd="true"`) produce exactly 3 commits following Red-Green-Refactor:
 
 ```
-test(02-01): RED - add failing tests for auth middleware
-feat(02-01): GREEN - implement auth middleware to pass tests
-refactor(02-01): REFACTOR - extract token verification helper
+test(auth): RED - add failing tests for auth middleware
+refactor(auth): GREEN - implement auth middleware to pass tests
+refactor(auth): REFACTOR - extract token verification helper
 ```
 
 ### Commit Preconditions
@@ -125,15 +140,15 @@ When an executor applies a deviation rule during a task, the deviation is includ
 ```bash
 # Standard task
 git add src/auth/discord.ts src/auth/types.ts
-git commit -m "feat(02-01): implement Discord OAuth client with token exchange"
+git commit -m "feat(auth): implement Discord OAuth client with token exchange"
 
 # Task that also installed a dependency (Rule 2)
 git add src/auth/discord.ts src/auth/types.ts package.json package-lock.json
-git commit -m "feat(02-01): implement Discord OAuth client with token exchange"
+git commit -m "feat(auth): implement Discord OAuth client with token exchange"
 
 # TDD RED
 git add tests/auth/discord.test.ts
-git commit -m "test(02-01): add failing tests for Discord OAuth flow"
+git commit -m "test(auth): add failing tests for Discord OAuth flow"
 ```
 
 ---

package/plugins/copilot-pbr/skills/begin/templates/config.json.tmpl

@@ -44,7 +44,7 @@
   },
   "git": {
     "branching": "none",
-    "commit_format": "{type}({phase}-{plan}): {description}",
+    "commit_format": "{type}({scope}): {description}",
     "phase_branch_template": "plan-build-run/phase-{phase}-{slug}",
     "milestone_branch_template": "plan-build-run/{milestone}-{slug}",
     "mode": "enabled"

package/plugins/copilot-pbr/skills/undo/SKILL.md

@@ -63,9 +63,9 @@ Present grouped output:
 ```
 Recent PBR commits (grouped by scope):
 
-[55-02] Phase 55, Plan 02
-  abc1234  feat(55-02): add undo skill
-  def5678  chore(55-02): register undo command
+[undo]
+  abc1234  feat(undo): add undo skill
+  def5678  chore(undo): register undo command
 
 [quick-003]
   ghi9012  fix(quick-003): fix hook path resolution
@@ -74,7 +74,7 @@ Recent PBR commits (grouped by scope):
   jkl3456  docs(planning): update roadmap phase 55
 ```
 
-For phase-plan scopes (NN-MM pattern), add a "Phase NN, Plan MM" annotation. For other scopes, show just the scope label.
+For descriptive scopes, show just the scope label. For phase-plan scopes (NN-MM pattern, from older commits), add a "Phase NN, Plan MM" annotation.
 
 ---
 
@@ -102,8 +102,8 @@ Display the commits that will be reverted:
 ```
 The following commits will be reverted (using git revert, NOT git reset):
 
-  abc1234  feat(55-02): add undo skill
-  def5678  chore(55-02): register undo command
+  abc1234  feat(undo): add undo skill
+  def5678  chore(undo): register undo command
 
 This creates new revert commits — your history is preserved.
 ```
@@ -125,7 +125,7 @@ git revert --no-commit {hash}
 ```
 
 After all reverts are staged, determine the commit message:
-- Extract scope from the first commit being reverted (e.g., `55-02`)
+- Extract scope from the first commit being reverted (e.g., `undo`, `auth`, `executor`)
 - If reverting a **single commit**: `revert({scope}): undo {original description}`
 - If reverting **multiple commits**: `revert({scope}): undo {N} commits from {scope}`
 

package/plugins/cursor-pbr/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.56.2",
+  "version": "2.56.3",
   "description": "Plan-Build-Run — Structured development workflow for Cursor. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/cursor-pbr/agents/executor.md

@@ -102,7 +102,7 @@ One task = one commit. Exception: TDD tasks get 3 commits (RED, GREEN, REFACTOR)
 ### Commit Format
 
 ```
-{type}({phase}-{plan}): {description}
+{type}({scope}): {description}
 ```
 
 | Type | When |
@@ -121,7 +121,7 @@ Stage only files listed in the task's `<files>`. If git commit fails with lock e
 When the plan frontmatter contains a non-empty `closes_issues` array, append issue-closing syntax to the **final** commit body for the plan:
 
 ```
-git commit -m "feat(01-02): implement user auth
+git commit -m "feat(auth): implement user auth
 
 Closes #42
 Closes #57"
@@ -219,9 +219,9 @@ When a task has `tdd="true"`, follow Red-Green-Refactor:
 
 | Phase | Action | Test Must | Commit | If Wrong |
 |-------|--------|-----------|--------|----------|
-| RED | Write test from `<done>` | FAIL | `test(NN-MM): RED - ...` | Passes? Fix test. |
-| GREEN | Minimal code to pass | PASS | `feat(NN-MM): GREEN - ...` | Fails? Fix code. |
-| REFACTOR | Clean up, keep behavior | PASS | `refactor(NN-MM): REFACTOR - ...` | Breaks? Revert. |
+| RED | Write test from `<done>` | FAIL | `test({scope}): RED - ...` | Passes? Fix test. |
+| GREEN | Minimal code to pass | PASS | `refactor({scope}): GREEN - ...` | Fails? Fix code. |
+| REFACTOR | Clean up, keep behavior | PASS | `refactor({scope}): REFACTOR - ...` | Breaks? Revert. |
 
 ---
 

package/plugins/cursor-pbr/agents/general.md

@@ -52,7 +52,7 @@ This agent is available for ad-hoc `Task()` calls from skills or custom orchestr
 
 All commits follow: `{type}({scope}): {description}`
 - **Types**: feat, fix, refactor, test, docs, chore, wip
-- **Scopes**: `{phase}-{plan}` (e.g., `03-01`), `quick-{NNN}`, `planning`
+- **Scopes**: descriptive word (e.g., `auth`, `api`, `executor`), `quick-{NNN}`, `planning`
 
 ## Self-Escalation
 

package/plugins/cursor-pbr/references/config-reference.md

@@ -151,7 +151,7 @@ Controls git integration and branching strategy.
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `branching` | string | `none` | Branching strategy: `none`, `phase`, `milestone`, `disabled` |
-| `commit_format` | string | `{type}({phase}-{plan}): {description}` | Commit message template |
+| `commit_format` | string | `{type}({scope}): {description}` | Commit message template. Use a short descriptive word as the scope (e.g., `auth`, `config`, `executor`) rather than phase-plan numbers. |
 | `phase_branch_template` | string | `plan-build-run/phase-{phase}-{slug}` | Phase branch name pattern |
 | `milestone_branch_template` | string | `plan-build-run/{milestone}-{slug}` | Milestone branch name pattern |
 | `mode` | string | `enabled` | Git mode: `enabled` or `disabled` |

package/plugins/cursor-pbr/references/git-integration.md

@@ -7,23 +7,22 @@ Plan-Build-Run's commit conventions, commit points, branching strategy, and hook
 ## Commit Message Format
 
 ```
-{type}({phase}-{plan}): {description}
+{type}({scope}): {description}
 ```
 
 ### Components
 
 | Part | Description | Example |
 |------|-------------|---------|
-| `{type}` | Conventional commit type | `feat`, `fix`, `test` |
-| `{phase}` | Phase number (zero-padded) | `02` |
-| `{plan}` | Plan number | `01` |
-| `{description}` | Imperative, lowercase description | `implement discord oauth client` |
+| `{type}` | Conventional commit type | `feat`, `fix`, `chore` |
+| `{scope}` | Descriptive word for the area of change | `auth`, `executor`, `changelog` |
+| `{description}` | Imperative, lowercase description | `add discord oauth flow` |
 
-The format is configurable via `config.json` at `git.commit_format`. The default is `{type}({phase}-{plan}): {description}`.
+The format is configurable via `config.json` at `git.commit_format`. The default is `{type}({scope}): {description}`.
 
 ### Full Example
 ```
-feat(02-01): implement discord oauth client
+feat(auth): implement discord oauth client
 ```
 
 ---
@@ -32,19 +31,35 @@ feat(02-01): implement discord oauth client
 
 | Type | When to Use | Example |
 |------|------------|---------|
-| `feat` | New feature or functionality | `feat(02-01): implement discord oauth client` |
-| `fix` | Bug fix (including during execution) | `fix(02-01): handle null user profile from discord api` |
-| `refactor` | Code restructuring, no behavior change | `refactor(02-01): extract token validation into helper` |
-| `test` | Adding or modifying tests | `test(02-01): add failing tests for discord oauth flow` |
-| `docs` | Documentation changes | `docs(03-02): add api endpoint documentation` |
-| `chore` | Build config, dependencies, tooling | `chore(01-01): configure typescript and eslint` |
-| `style` | Formatting, whitespace (no logic change) | `style(02-01): fix import ordering` |
+| `feat` | New feature or functionality | `feat(auth): implement discord oauth client` |
+| `fix` | Bug fix (including during execution) | `fix(api): handle null user profile from discord` |
+| `refactor` | Code restructuring, no behavior change | `refactor(auth): extract token validation into helper` |
+| `test` | Adding or modifying tests | `test(auth): add failing tests for oauth flow` |
+| `docs` | Documentation changes | `docs(planning): add api endpoint documentation` |
+| `chore` | Build config, dependencies, tooling | `chore(deps): configure typescript and eslint` |
+| `style` | Formatting, whitespace (no logic change) | `style(auth): fix import ordering` |
+
+---
+
+## Commit Type Discipline
+
+| Type | Use For | Appears in Changelog |
+|------|---------|---------------------|
+| `feat` | User-visible features ONLY (new commands, new config options, changed behavior users notice) | YES |
+| `fix` | Bug fixes users would notice | YES |
+| `refactor` | Internal restructuring, TDD GREEN commits, code cleanup | No |
+| `test` | Test additions including TDD RED commits | No |
+| `docs` | Documentation (hidden — mostly planning artifacts) | No |
+| `chore` | Build config, deps, tooling, internal scaffolding | No |
+| `wip` | Work in progress (use sparingly) | No |
+
+**TDD commits**: RED phase → `test({scope}): RED - ...`, GREEN phase → `refactor({scope}): GREEN - ...`, REFACTOR phase → `refactor({scope}): REFACTOR - ...`
 
 ---
 
 ## Special Commit Scopes
 
-Beyond the standard `{phase}-{plan}` scope, Plan-Build-Run recognizes these additional patterns:
+Beyond descriptive scopes, Plan-Build-Run recognizes these additional patterns:
 
 | Pattern | When Used | Example |
 |---------|-----------|---------|
@@ -84,9 +99,9 @@ Each successfully completed plan task gets exactly one atomic commit. No more, n
 TDD tasks (`tdd="true"`) produce exactly 3 commits following Red-Green-Refactor:
 
 ```
-test(02-01): RED - add failing tests for auth middleware
-feat(02-01): GREEN - implement auth middleware to pass tests
-refactor(02-01): REFACTOR - extract token verification helper
+test(auth): RED - add failing tests for auth middleware
+refactor(auth): GREEN - implement auth middleware to pass tests
+refactor(auth): REFACTOR - extract token verification helper
 ```
 
 ### Commit Preconditions
@@ -125,15 +140,15 @@ When an executor applies a deviation rule during a task, the deviation is includ
 ```bash
 # Standard task
 git add src/auth/discord.ts src/auth/types.ts
-git commit -m "feat(02-01): implement Discord OAuth client with token exchange"
+git commit -m "feat(auth): implement Discord OAuth client with token exchange"
 
 # Task that also installed a dependency (Rule 2)
 git add src/auth/discord.ts src/auth/types.ts package.json package-lock.json
-git commit -m "feat(02-01): implement Discord OAuth client with token exchange"
+git commit -m "feat(auth): implement Discord OAuth client with token exchange"
 
 # TDD RED
 git add tests/auth/discord.test.ts
-git commit -m "test(02-01): add failing tests for Discord OAuth flow"
+git commit -m "test(auth): add failing tests for Discord OAuth flow"
 ```
 
 ---

package/plugins/cursor-pbr/skills/begin/templates/config.json.tmpl

@@ -44,7 +44,7 @@
   },
   "git": {
     "branching": "none",
-    "commit_format": "{type}({phase}-{plan}): {description}",
+    "commit_format": "{type}({scope}): {description}",
     "phase_branch_template": "plan-build-run/phase-{phase}-{slug}",
     "milestone_branch_template": "plan-build-run/{milestone}-{slug}",
     "mode": "enabled"