conventional-git 1.3.0__tar.gz → 2.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (179) hide show
  1. {conventional_git-1.3.0 → conventional_git-2.1.1}/.claude-plugin/plugin.json +1 -1
  2. {conventional_git-1.3.0 → conventional_git-2.1.1}/.gitignore +3 -0
  3. {conventional_git-1.3.0 → conventional_git-2.1.1}/.pre-commit-config.yaml +7 -0
  4. {conventional_git-1.3.0 → conventional_git-2.1.1}/AGENTS.md +11 -1
  5. {conventional_git-1.3.0 → conventional_git-2.1.1}/Makefile +23 -2
  6. {conventional_git-1.3.0 → conventional_git-2.1.1}/PKG-INFO +22 -18
  7. {conventional_git-1.3.0 → conventional_git-2.1.1}/README.md +21 -17
  8. {conventional_git-1.3.0 → conventional_git-2.1.1}/dictionary.txt +2 -0
  9. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/agents/agent-skills-format.md +2 -3
  10. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/agents/claude-code-install-scopes.md +1 -2
  11. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/agents/claude-code-marketplace-install.md +1 -2
  12. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/agents/claude-code-plugin-updates.md +1 -2
  13. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/agents/claude-code-shell-install.md +1 -2
  14. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/agents/claude-code-skill-invocation.md +1 -2
  15. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/agents/install-channels.md +2 -3
  16. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/agents/npx-skills-install.md +1 -2
  17. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/agents/npx-skills-manage.md +1 -2
  18. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/agents/opencode-mcp-config.md +1 -2
  19. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/agents/opencode-mcp-server.md +0 -1
  20. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/agents/opencode-skill-discovery.md +1 -2
  21. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/agents/opencode-skill-permissions.md +1 -2
  22. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/agents/plugin-identity.md +6 -5
  23. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/conventions/claude-md-check.md +1 -1
  24. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/conventions/help-check.md +1 -1
  25. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/conventions/index.md +4 -0
  26. conventional_git-2.1.1/docs/conventions/tag-vocabulary.md +28 -0
  27. conventional_git-2.1.1/docs/conventions/versioning.md +47 -0
  28. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/enforcement/attribution-trailers.md +3 -2
  29. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/enforcement/git-hooks.md +1 -1
  30. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/enforcement/hook-install-path.md +1 -1
  31. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/enforcement/pre-commit-local-hooks.md +1 -1
  32. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/gitlint/install.md +1 -1
  33. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/log.md +44 -18
  34. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/mcp/index.md +4 -0
  35. conventional_git-2.1.1/docs/mcp/no-auth-tools.md +23 -0
  36. conventional_git-2.1.1/docs/mcp/out-of-band-auth.md +39 -0
  37. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/mcp/plugin-bundled-server.md +4 -0
  38. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/mcp/suggest-commit-message.md +29 -0
  39. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/python/interpreter-source.md +1 -1
  40. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/toolchain/index.md +2 -0
  41. conventional_git-2.1.1/docs/toolchain/layering-rule.md +28 -0
  42. conventional_git-2.1.1/docs/toolchain/retag-notes.md +29 -0
  43. {conventional_git-1.3.0 → conventional_git-2.1.1}/mk/python.mk +8 -1
  44. conventional_git-2.1.1/okf-base.yaml +42 -0
  45. {conventional_git-1.3.0 → conventional_git-2.1.1}/package.json +2 -2
  46. {conventional_git-1.3.0 → conventional_git-2.1.1}/pnpm-lock.yaml +120 -120
  47. {conventional_git-1.3.0 → conventional_git-2.1.1}/pyproject.toml +4 -3
  48. conventional_git-2.1.1/skills/conventional-auth/SKILL.md +67 -0
  49. {conventional_git-1.3.0 → conventional_git-2.1.1}/skills/conventional-branch/SKILL.md +1 -3
  50. {conventional_git-1.3.0 → conventional_git-2.1.1}/skills/conventional-commit/SKILL.md +8 -9
  51. conventional_git-2.1.1/skills/conventional-suggest/SKILL.md +86 -0
  52. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/adapters/gitlint_rules.py +6 -3
  53. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/cli/check.py +1 -0
  54. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/cli/create.py +13 -14
  55. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/commit/rules.py +3 -1
  56. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/commit/vocabulary.py +2 -0
  57. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/config.py +2 -0
  58. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/helpers.py +3 -0
  59. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/mcp/server.py +1 -0
  60. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_cli_smoke.py +53 -4
  61. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_commit_rules.py +18 -0
  62. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_commit_vocabulary.py +15 -0
  63. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_config.py +20 -0
  64. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_gitlint_rules.py +19 -0
  65. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_helpers.py +16 -0
  66. conventional_git-2.1.1/tools/docs-retag.py +141 -0
  67. {conventional_git-1.3.0 → conventional_git-2.1.1}/uv.lock +12 -12
  68. conventional_git-1.3.0/docs/toolchain/layering-rule.md +0 -35
  69. {conventional_git-1.3.0 → conventional_git-2.1.1}/.claude-plugin/marketplace.json +0 -0
  70. {conventional_git-1.3.0 → conventional_git-2.1.1}/.editorconfig +0 -0
  71. {conventional_git-1.3.0 → conventional_git-2.1.1}/.github/dependabot.yml +0 -0
  72. {conventional_git-1.3.0 → conventional_git-2.1.1}/.github/workflows/ci.yml +0 -0
  73. {conventional_git-1.3.0 → conventional_git-2.1.1}/.github/workflows/publish.yml +0 -0
  74. {conventional_git-1.3.0 → conventional_git-2.1.1}/.github/workflows/python.yml +0 -0
  75. {conventional_git-1.3.0 → conventional_git-2.1.1}/.markdownlint-cli2.jsonc +0 -0
  76. {conventional_git-1.3.0 → conventional_git-2.1.1}/.markdownlint.yaml +0 -0
  77. {conventional_git-1.3.0 → conventional_git-2.1.1}/.mcp.json +0 -0
  78. {conventional_git-1.3.0 → conventional_git-2.1.1}/.pre-commit-hooks.yaml +0 -0
  79. {conventional_git-1.3.0 → conventional_git-2.1.1}/CONTRIBUTING.md +0 -0
  80. {conventional_git-1.3.0 → conventional_git-2.1.1}/LICENSE +0 -0
  81. {conventional_git-1.3.0 → conventional_git-2.1.1}/checkmake.ini +0 -0
  82. {conventional_git-1.3.0 → conventional_git-2.1.1}/cspell.config.yaml +0 -0
  83. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/agents/index.md +0 -0
  84. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/architecture/index.md +0 -0
  85. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/architecture/optional-extras.md +0 -0
  86. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/architecture/three-layers.md +0 -0
  87. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/architecture/validation-vs-generation.md +0 -0
  88. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/architecture/violation-contract.md +0 -0
  89. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/architecture/vocabulary-as-data.md +0 -0
  90. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/conventions/commits-and-branches.md +0 -0
  91. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/conventions/commits-check.md +0 -0
  92. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/enforcement/branch-name-gap.md +0 -0
  93. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/enforcement/ci-recipe.md +0 -0
  94. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/enforcement/commitizen-adapter.md +0 -0
  95. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/enforcement/house-rules.md +0 -0
  96. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/enforcement/index.md +0 -0
  97. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/enforcement/pre-commit-framework.md +0 -0
  98. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/enforcement/skill-vocabulary-copies.md +0 -0
  99. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/gitlint/behavior-vs-cli.md +0 -0
  100. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/gitlint/extra-path.md +0 -0
  101. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/gitlint/index.md +0 -0
  102. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/gitlint/recommended-config.md +0 -0
  103. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/gitlint/when-to-use.md +0 -0
  104. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/gitlint/wiring.md +0 -0
  105. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/index.md +0 -0
  106. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/mcp/describe-convention.md +0 -0
  107. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/mcp/self-correction-loop.md +0 -0
  108. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/mcp/server-install.md +0 -0
  109. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/mcp/validate-tools.md +0 -0
  110. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/python/index.md +0 -0
  111. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/python/pyproject-defaults.md +0 -0
  112. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/release/index.md +0 -0
  113. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/release/pypi-trusted-publishing.md +0 -0
  114. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/suggestions/apply-does-not-commit.md +0 -0
  115. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/suggestions/data-egress.md +0 -0
  116. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/suggestions/index.md +0 -0
  117. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/suggestions/keyring-scope.md +0 -0
  118. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/suggestions/llm-extra-install.md +0 -0
  119. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/suggestions/provider-fallback.md +0 -0
  120. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/suggestions/providers-and-credentials.md +0 -0
  121. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/toolchain/extras-self-reference.md +0 -0
  122. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/toolchain/rejected-install-backends.md +0 -0
  123. {conventional_git-1.3.0 → conventional_git-2.1.1}/docs/toolchain/sh-uid-unused.md +0 -0
  124. {conventional_git-1.3.0 → conventional_git-2.1.1}/mise.toml +0 -0
  125. {conventional_git-1.3.0 → conventional_git-2.1.1}/mk/.gitkeep +0 -0
  126. {conventional_git-1.3.0 → conventional_git-2.1.1}/mk/conventional-git.mk +0 -0
  127. {conventional_git-1.3.0 → conventional_git-2.1.1}/pnpm-workspace.yaml +0 -0
  128. {conventional_git-1.3.0 → conventional_git-2.1.1}/skills/conventional-branch/references/branch-types.csv +0 -0
  129. {conventional_git-1.3.0 → conventional_git-2.1.1}/skills/conventional-commit/references/commit-types.csv +0 -0
  130. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/__init__.py +0 -0
  131. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/adapters/__init__.py +0 -0
  132. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/adapters/commitizen_config.py +0 -0
  133. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/branch/__init__.py +0 -0
  134. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/branch/grammar.py +0 -0
  135. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/branch/rules.py +0 -0
  136. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/branch/vocabulary.py +0 -0
  137. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/cli/__init__.py +0 -0
  138. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/cli/app.py +0 -0
  139. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/cli/auth.py +0 -0
  140. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/cli/capabilities.py +0 -0
  141. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/cli/hook.py +0 -0
  142. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/cli/mcp.py +0 -0
  143. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/commit/__init__.py +0 -0
  144. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/commit/compose.py +0 -0
  145. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/commit/grammar.py +0 -0
  146. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/csv_columns.py +0 -0
  147. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/data/__init__.py +0 -0
  148. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/data/branch-exempt-prefixes.csv +0 -0
  149. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/data/branch-trunks.csv +0 -0
  150. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/data/branch-types.csv +0 -0
  151. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/data/commit-attribution.csv +0 -0
  152. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/data/commit-types.csv +0 -0
  153. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/generation/__init__.py +0 -0
  154. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/generation/credentials.py +0 -0
  155. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/generation/diff.py +0 -0
  156. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/generation/heuristic.py +0 -0
  157. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/generation/protocol.py +0 -0
  158. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/generation/typesafe.py +0 -0
  159. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/mcp/__init__.py +0 -0
  160. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/py.typed +0 -0
  161. {conventional_git-1.3.0 → conventional_git-2.1.1}/src/conventional_git/violations.py +0 -0
  162. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/__init__.py +0 -0
  163. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_branch_rules.py +0 -0
  164. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_branch_vocabulary.py +0 -0
  165. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_cli_auth.py +0 -0
  166. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_cli_capabilities.py +0 -0
  167. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_cli_hook.py +0 -0
  168. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_commit_compose.py +0 -0
  169. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_credentials.py +0 -0
  170. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_diff.py +0 -0
  171. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_generation_suggest.py +0 -0
  172. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_heuristic.py +0 -0
  173. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_mcp_server.py +0 -0
  174. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_plugin_version.py +0 -0
  175. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_sh_uid_unused.py +0 -0
  176. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_skill_vocabularies.py +0 -0
  177. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_typesafe_client_factory.py +0 -0
  178. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_typesafe_provider.py +0 -0
  179. {conventional_git-1.3.0 → conventional_git-2.1.1}/tests/test_violation_code_coverage.py +0 -0
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "conventional-git",
3
- "version": "1.3.0",
3
+ "version": "2.1.1",
4
4
  "description": "Conventional Commits and Conventional Branch skills for Claude Code",
5
5
  "author": {
6
6
  "name": "G.A.JAGUAR",
@@ -7,6 +7,9 @@ mise.local.toml
7
7
  # Obsidian vault metadata (docs/ is opened directly as a vault)
8
8
  .obsidian/
9
9
 
10
+ # Answers and batches of `make docs-retag`
11
+ .cache/
12
+
10
13
  # Created by https://www.toptal.com/developers/gitignore/api/linux,macos,jetbrains+all,visualstudiocode,node,python
11
14
  # Edit at https://www.toptal.com/developers/gitignore?templates=linux,macos,jetbrains+all,visualstudiocode,node,python
12
15
 
@@ -27,6 +27,13 @@ repos:
27
27
  language: system
28
28
  pass_filenames: false
29
29
 
30
+ - id: docs-lint
31
+ name: okflint
32
+ entry: make docs-lint
33
+ language: system
34
+ files: ^(docs/.*\.md|okf-base\.yaml)$
35
+ pass_filenames: false
36
+
30
37
  - id: conventional-commit-msg
31
38
  name: conventional-git commit message
32
39
  entry: uvx conventional-git@latest check commit --file
@@ -47,13 +47,20 @@ Once a pull request is open, the agent MUST:
47
47
  3. Delete the branch on the remote and locally.
48
48
  4. Switch back to the base branch, pull it and run `git fetch --prune`.
49
49
 
50
+ ## Versioning and releases
51
+
52
+ - Decide every version bump, tag and release as
53
+ [`docs/conventions/versioning.md`](docs/conventions/versioning.md) defines;
54
+ it is the only place those rules live.
55
+
50
56
  ## Documentation
51
57
 
52
58
  - Follow the organization's shared documentation-writing guide, kept in one
53
59
  place rather than copied into this repository so it cannot drift from other
54
60
  projects that follow the same guide.
55
61
  - Add a new `docs/` note to its directory's `index.md` and, by file name, to
56
- [`docs/log.md`](docs/log.md).
62
+ [`docs/log.md`](docs/log.md); `make docs-lint` fails on a missing field or a
63
+ broken link.
57
64
  - Cover exactly one concept per note.
58
65
  - Write a note only when it explains something a reader cannot already get
59
66
  from `make help`, a linter's own message, or the configuration it comes
@@ -103,3 +110,6 @@ feature.
103
110
  [`docs/python/pyproject-defaults.md`](docs/python/pyproject-defaults.md).
104
111
  - Keep the spec core free of `git` imports and `SystemExit`. Returning a
105
112
  `Report` is the contract; only front-ends turn violations into exit codes.
113
+ - Tag a minor or major bump with `make release-tag` after its pull request
114
+ merges, as [`docs/conventions/versioning.md`](docs/conventions/versioning.md)
115
+ describes; the target tags the base branch as `v<project.version>`.
@@ -13,6 +13,11 @@ FILES ?=
13
13
  # docs/conventions/commits-check.md.
14
14
  BASE ?= origin/main
15
15
  CONVENTIONAL_GIT ?= uvx conventional-git@latest
16
+ # Pinned, not @latest: a linter's verdict changes between versions. See
17
+ # docs/toolchain/okflint.md and docs/documentation/retag-notes.md.
18
+ OKFLINT ?= uvx okflint@0.4.1
19
+ TYPESAFE ?= uvx --from typesafe-unofficial-cli@1.1.0 typesafe
20
+ DOCS_RETAG := uv run --script tools/docs-retag.py
16
21
  BRANCH ?= $(or $(GITHUB_HEAD_REF),$(shell git branch --show-current))
17
22
 
18
23
  .DEFAULT_GOAL := help
@@ -81,9 +86,12 @@ claude-md-check: ## Fail if a CLAUDE.md exists, since AGENTS.md is the only agen
81
86
  @found=$$(git ls-files --cached --others --exclude-standard | grep -E '(^|/)CLAUDE\.md$$' || true); \
82
87
  test -z "$$found" || { echo "CLAUDE.md found; fold it into AGENTS.md and delete it:" >&2; echo "$$found" >&2; exit 1; }
83
88
 
84
- check: makefile-lint md-lint spell commits-check help-check claude-md-check $(LANG_CHECK_TARGETS) ## Run the full read-only validation gate
89
+ docs-lint: ## Validate docs/ as an OKF bundle with okflint — see docs/toolchain/okflint.md
90
+ @$(OKFLINT) validate
85
91
 
86
- .PHONY: makefile-lint md-lint spell commits-check help-check claude-md-check check
92
+ check: makefile-lint md-lint spell docs-lint commits-check help-check claude-md-check $(LANG_CHECK_TARGETS) ## Run the full read-only validation gate
93
+
94
+ .PHONY: makefile-lint md-lint spell docs-lint commits-check help-check claude-md-check check
87
95
 
88
96
  ##@ Writable fixes (mutate files in place)
89
97
 
@@ -114,3 +122,16 @@ fix-unsafe: _md-fix-scoped $(LANG_FIX_UNSAFE_TARGETS) ## Apply all auto-fixes, i
114
122
  test: $(LANG_TEST_TARGETS) ## Run the test suite
115
123
 
116
124
  .PHONY: test
125
+
126
+ ##@ Docs tagging (optional, billed — not part of check)
127
+
128
+ docs-retag: ## Ask TypeSafe which tags each docs/ note carries, then show a dry run — one billed request per note
129
+ @$(DOCS_RETAG) build
130
+ @$(TYPESAFE) -o jsonl ask --states-file .cache/docs-retag/states.jsonl --questions-file .cache/docs-retag/questions.json --concurrency 4 > .cache/docs-retag/answers.jsonl
131
+ @$(DOCS_RETAG) apply
132
+
133
+ docs-retag-apply: ## Write the tags from the last docs-retag run into the notes, then validate docs/
134
+ @$(DOCS_RETAG) apply --write
135
+ @$(MAKE) docs-lint
136
+
137
+ .PHONY: docs-retag docs-retag-apply
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: conventional-git
3
- Version: 1.3.0
3
+ Version: 2.1.1
4
4
  Summary: Conventional Commits and Conventional Branch enforcement, validation, and generation
5
5
  Project-URL: Repository, https://github.com/gajaguar/conventional-git
6
6
  Project-URL: Issues, https://github.com/gajaguar/conventional-git/issues
@@ -146,9 +146,6 @@ conventional-git create branch --type feature --description "add login"
146
146
  # feature/add-login
147
147
  ```
148
148
 
149
- Use `--dry-run` when you need the generated value without taking further
150
- action. The current implementation prints the value in either mode.
151
-
152
149
  ### Enforce
153
150
 
154
151
  Install `commit-msg`, `pre-commit`, and `pre-push` hooks in a repository:
@@ -170,8 +167,9 @@ credential, `create suggest` always falls back to the built-in heuristic
170
167
  provider and prints a notice; it never fails the command:
171
168
 
172
169
  ```bash
173
- git diff --cached | conventional-git create suggest --diff-file -
170
+ conventional-git create suggest
174
171
  conventional-git create suggest --diff-file changes.diff --apply
172
+ git diff main... | conventional-git create suggest --diff-file -
175
173
  ```
176
174
 
177
175
  With the `llm` extra installed and a credential available, `create suggest`
@@ -218,7 +216,10 @@ uvx --from 'conventional-git[mcp]' conventional-git-mcp
218
216
  ```
219
217
 
220
218
  The server exposes `validate_commit_message`, `validate_branch_name`,
221
- `describe_convention`, and `suggest_commit_message`. See
219
+ `describe_convention`, and `suggest_commit_message`. The server has no auth
220
+ tools: for `suggest_commit_message` to use `jev`, run
221
+ `conventional-git auth login` first and launch it with the `llm` extra (see
222
+ [`docs/mcp/out-of-band-auth.md`](docs/mcp/out-of-band-auth.md)). See
222
223
  [`docs/mcp/index.md`](docs/mcp/index.md).
223
224
 
224
225
  ## Agents
@@ -229,7 +230,8 @@ directory. See [`docs/agents/index.md`](docs/agents/index.md) for the full
229
230
  install guide; one command per channel.
230
231
 
231
232
  **Claude Code**: add the marketplace, then install the plugin. It bundles
232
- `conventional-commit`, `conventional-branch`, and the MCP server:
233
+ `conventional-commit`, `conventional-branch`, `conventional-suggest`,
234
+ `conventional-auth`, and the MCP server:
233
235
 
234
236
  ```text
235
237
  /plugin marketplace add gajaguar/conventional-git
@@ -267,8 +269,8 @@ return `1`.
267
269
  | :------------- | ---------------------------------------------------------------------------------------- | ------------: |
268
270
  | check commit | `-m, --message`; `-f, --file`; `--types-csv` | 0 or 1 |
269
271
  | check branch | `-n, --name`; `--types-csv` | 0 or 1 |
270
- | create commit | `--type`; `--description`; `--scope`; `--body`; `--breaking`; `--types-csv`; `--dry-run` | 0 or 1 |
271
- | create branch | `--type`; `--description`; `--types-csv`; `--dry-run` | 0 or 1 |
272
+ | create commit | `--type`; `--description`; `--scope`; `--body`; `--breaking`; `--types-csv` | 0 or 1 |
273
+ | create branch | `--type`; `--description`; `--types-csv` | 0 or 1 |
272
274
  | create suggest | `--diff-file`; `--provider`; `--apply` | 0 or 1 |
273
275
  | hook install | `--target`; `--force` | 0 or 1 |
274
276
  | hook uninstall | `--target` | 0 |
@@ -284,13 +286,14 @@ Use `conventional-git <command> --help` for the full option descriptions.
284
286
 
285
287
  Create `.conventional-git.toml` in the current repository:
286
288
 
287
- | Key | Default | Purpose |
288
- | :--------------------------------- | ------------- | -------------------------- |
289
- | `[commit] attribution_patterns` | built-in list | Extra attribution regexes |
290
- | `[commit] type_overrides` | `[]` | Extra commit types |
291
- | `[branch] type_overrides` | `[]` | Extra branch types |
292
- | `[branch] trunk_overrides` | `[]` | Extra trunk branch names |
293
- | `[branch] exempt_prefix_overrides` | `[]` | Extra exempt name prefixes |
289
+ | Key | Default | Purpose |
290
+ | :---------------------------------------------- | ------------- | ---------------------------------- |
291
+ | `[commit] attribution_patterns` | built-in list | Extra attribution regexes |
292
+ | `[commit] disable_default_attribution_patterns` | `false` | Skip the built-in attribution list |
293
+ | `[commit] type_overrides` | `[]` | Extra commit types |
294
+ | `[branch] type_overrides` | `[]` | Extra branch types |
295
+ | `[branch] trunk_overrides` | `[]` | Extra trunk branch names |
296
+ | `[branch] exempt_prefix_overrides` | `[]` | Extra exempt name prefixes |
294
297
 
295
298
  Relative CSV paths in `type_overrides` / `trunk_overrides` /
296
299
  `exempt_prefix_overrides` are resolved
@@ -298,7 +301,8 @@ against the directory containing `.conventional-git.toml`, not the process's
298
301
  current directory. Every consumer that loads the file — the CLI, the MCP
299
302
  server, and the gitlint adapter — honors it. See
300
303
  [`docs/enforcement/attribution-trailers.md`](docs/enforcement/attribution-trailers.md)
301
- for what `attribution_patterns` extends.
304
+ for what `attribution_patterns` extends and how
305
+ `disable_default_attribution_patterns` turns the built-in list off.
302
306
 
303
307
  The `--types-csv` option extends the default vocabulary; it does not replace
304
308
  it. Vocabulary files live in `data/{commit,branch}-types.csv`.
@@ -335,7 +339,7 @@ and render its output. See [`docs/architecture/index.md`](docs/architecture/inde
335
339
  │ ├── adapters/{gitlint_rules,commitizen_config}.py
336
340
  │ ├── cli/{app,auth,check,create,hook,mcp}.py
337
341
  │ └── mcp/server.py
338
- ├── skills/conventional-{commit,branch}/SKILL.md
342
+ ├── skills/conventional-{commit,branch,suggest,auth}/SKILL.md
339
343
  └── tests/
340
344
  ```
341
345
 
@@ -125,9 +125,6 @@ conventional-git create branch --type feature --description "add login"
125
125
  # feature/add-login
126
126
  ```
127
127
 
128
- Use `--dry-run` when you need the generated value without taking further
129
- action. The current implementation prints the value in either mode.
130
-
131
128
  ### Enforce
132
129
 
133
130
  Install `commit-msg`, `pre-commit`, and `pre-push` hooks in a repository:
@@ -149,8 +146,9 @@ credential, `create suggest` always falls back to the built-in heuristic
149
146
  provider and prints a notice; it never fails the command:
150
147
 
151
148
  ```bash
152
- git diff --cached | conventional-git create suggest --diff-file -
149
+ conventional-git create suggest
153
150
  conventional-git create suggest --diff-file changes.diff --apply
151
+ git diff main... | conventional-git create suggest --diff-file -
154
152
  ```
155
153
 
156
154
  With the `llm` extra installed and a credential available, `create suggest`
@@ -197,7 +195,10 @@ uvx --from 'conventional-git[mcp]' conventional-git-mcp
197
195
  ```
198
196
 
199
197
  The server exposes `validate_commit_message`, `validate_branch_name`,
200
- `describe_convention`, and `suggest_commit_message`. See
198
+ `describe_convention`, and `suggest_commit_message`. The server has no auth
199
+ tools: for `suggest_commit_message` to use `jev`, run
200
+ `conventional-git auth login` first and launch it with the `llm` extra (see
201
+ [`docs/mcp/out-of-band-auth.md`](docs/mcp/out-of-band-auth.md)). See
201
202
  [`docs/mcp/index.md`](docs/mcp/index.md).
202
203
 
203
204
  ## Agents
@@ -208,7 +209,8 @@ directory. See [`docs/agents/index.md`](docs/agents/index.md) for the full
208
209
  install guide; one command per channel.
209
210
 
210
211
  **Claude Code**: add the marketplace, then install the plugin. It bundles
211
- `conventional-commit`, `conventional-branch`, and the MCP server:
212
+ `conventional-commit`, `conventional-branch`, `conventional-suggest`,
213
+ `conventional-auth`, and the MCP server:
212
214
 
213
215
  ```text
214
216
  /plugin marketplace add gajaguar/conventional-git
@@ -246,8 +248,8 @@ return `1`.
246
248
  | :------------- | ---------------------------------------------------------------------------------------- | ------------: |
247
249
  | check commit | `-m, --message`; `-f, --file`; `--types-csv` | 0 or 1 |
248
250
  | check branch | `-n, --name`; `--types-csv` | 0 or 1 |
249
- | create commit | `--type`; `--description`; `--scope`; `--body`; `--breaking`; `--types-csv`; `--dry-run` | 0 or 1 |
250
- | create branch | `--type`; `--description`; `--types-csv`; `--dry-run` | 0 or 1 |
251
+ | create commit | `--type`; `--description`; `--scope`; `--body`; `--breaking`; `--types-csv` | 0 or 1 |
252
+ | create branch | `--type`; `--description`; `--types-csv` | 0 or 1 |
251
253
  | create suggest | `--diff-file`; `--provider`; `--apply` | 0 or 1 |
252
254
  | hook install | `--target`; `--force` | 0 or 1 |
253
255
  | hook uninstall | `--target` | 0 |
@@ -263,13 +265,14 @@ Use `conventional-git <command> --help` for the full option descriptions.
263
265
 
264
266
  Create `.conventional-git.toml` in the current repository:
265
267
 
266
- | Key | Default | Purpose |
267
- | :--------------------------------- | ------------- | -------------------------- |
268
- | `[commit] attribution_patterns` | built-in list | Extra attribution regexes |
269
- | `[commit] type_overrides` | `[]` | Extra commit types |
270
- | `[branch] type_overrides` | `[]` | Extra branch types |
271
- | `[branch] trunk_overrides` | `[]` | Extra trunk branch names |
272
- | `[branch] exempt_prefix_overrides` | `[]` | Extra exempt name prefixes |
268
+ | Key | Default | Purpose |
269
+ | :---------------------------------------------- | ------------- | ---------------------------------- |
270
+ | `[commit] attribution_patterns` | built-in list | Extra attribution regexes |
271
+ | `[commit] disable_default_attribution_patterns` | `false` | Skip the built-in attribution list |
272
+ | `[commit] type_overrides` | `[]` | Extra commit types |
273
+ | `[branch] type_overrides` | `[]` | Extra branch types |
274
+ | `[branch] trunk_overrides` | `[]` | Extra trunk branch names |
275
+ | `[branch] exempt_prefix_overrides` | `[]` | Extra exempt name prefixes |
273
276
 
274
277
  Relative CSV paths in `type_overrides` / `trunk_overrides` /
275
278
  `exempt_prefix_overrides` are resolved
@@ -277,7 +280,8 @@ against the directory containing `.conventional-git.toml`, not the process's
277
280
  current directory. Every consumer that loads the file — the CLI, the MCP
278
281
  server, and the gitlint adapter — honors it. See
279
282
  [`docs/enforcement/attribution-trailers.md`](docs/enforcement/attribution-trailers.md)
280
- for what `attribution_patterns` extends.
283
+ for what `attribution_patterns` extends and how
284
+ `disable_default_attribution_patterns` turns the built-in list off.
281
285
 
282
286
  The `--types-csv` option extends the default vocabulary; it does not replace
283
287
  it. Vocabulary files live in `data/{commit,branch}-types.csv`.
@@ -314,7 +318,7 @@ and render its output. See [`docs/architecture/index.md`](docs/architecture/inde
314
318
  │ ├── adapters/{gitlint_rules,commitizen_config}.py
315
319
  │ ├── cli/{app,auth,check,create,hook,mcp}.py
316
320
  │ └── mcp/server.py
317
- ├── skills/conventional-{commit,branch}/SKILL.md
321
+ ├── skills/conventional-{commit,branch,suggest,auth}/SKILL.md
318
322
  └── tests/
319
323
  ```
320
324
 
@@ -42,3 +42,5 @@ unbypassable
42
42
  uv
43
43
  venv
44
44
  vocabulary
45
+ okflint
46
+ retag
@@ -2,10 +2,9 @@
2
2
  type: reference
3
3
  title: Agent Skills format
4
4
  description: SKILL.md frontmatter fields and their constraints, progressive disclosure, and the optional references/ subdirectory.
5
- tags: [agents, skills]
5
+ tags: [agents, skills, documentation]
6
6
  status: stable
7
- generated: { by: claude-code/claude-opus-5-5, at: 2026-09-29T00:00:00Z }
8
- stale_after: 2027-03-29T00:00:00Z
7
+ stale_after: 2027-03-29
9
8
  sources:
10
9
  - id: agentskills-spec
11
10
  resource: https://agentskills.io/specification
@@ -4,8 +4,7 @@ title: Claude Code install scopes
4
4
  description: user, project, and local scopes — which settings file each writes to, the precedence order, and when each is the right choice.
5
5
  tags: [agents, claude-code]
6
6
  status: stable
7
- generated: { by: claude-code/claude-opus-5-5, at: 2026-09-29T00:00:00Z }
8
- stale_after: 2027-03-29T00:00:00Z
7
+ stale_after: 2027-03-29
9
8
  sources:
10
9
  - id: claude-discover-plugins
11
10
  resource: https://code.claude.com/docs/en/discover-plugins
@@ -4,8 +4,7 @@ title: Installing through the Claude Code marketplace
4
4
  description: Add a marketplace and install a plugin from it inside a Claude Code session, including the one-step form and the reload.
5
5
  tags: [agents, claude-code]
6
6
  status: stable
7
- generated: { by: claude-code/claude-opus-5-5, at: 2026-09-29T00:00:00Z }
8
- stale_after: 2027-03-29T00:00:00Z
7
+ stale_after: 2027-03-29
9
8
  sources:
10
9
  - id: claude-discover-plugins
11
10
  resource: https://code.claude.com/docs/en/discover-plugins
@@ -4,8 +4,7 @@ title: Updating and uninstalling Claude Code plugins
4
4
  description: Auto-update is off by default for third-party marketplaces, so update by hand and reload; uninstall the plugin and remove the marketplace when you are done.
5
5
  tags: [agents, claude-code]
6
6
  status: stable
7
- generated: { by: claude-code/claude-opus-5-5, at: 2026-09-29T00:00:00Z }
8
- stale_after: 2027-03-29T00:00:00Z
7
+ stale_after: 2027-03-29
9
8
  sources:
10
9
  - id: claude-discover-plugins
11
10
  resource: https://code.claude.com/docs/en/discover-plugins
@@ -4,8 +4,7 @@ title: Installing from a script or CI
4
4
  description: The claude plugin CLI installs and manages plugins from your shell, with user scope by default and a --yes flag for command-source prompts.
5
5
  tags: [agents, claude-code, ci]
6
6
  status: stable
7
- generated: { by: claude-code/claude-opus-5-5, at: 2026-09-29T00:00:00Z }
8
- stale_after: 2027-03-29T00:00:00Z
7
+ stale_after: 2027-03-29
9
8
  sources:
10
9
  - id: claude-discover-plugins
11
10
  resource: https://code.claude.com/docs/en/discover-plugins
@@ -4,8 +4,7 @@ title: Invoking a Claude Code skill
4
4
  description: The /<plugin>:<skill> slash form, automatic triggering by description, and three ways to verify a plugin skill is installed.
5
5
  tags: [agents, claude-code, skills]
6
6
  status: stable
7
- generated: { by: claude-code/claude-opus-5-5, at: 2026-09-29T00:00:00Z }
8
- stale_after: 2027-03-29T00:00:00Z
7
+ stale_after: 2027-03-29
9
8
  sources:
10
9
  - id: claude-skills
11
10
  resource: https://code.claude.com/docs/en/skills
@@ -2,10 +2,9 @@
2
2
  type: guideline
3
3
  title: Install channels
4
4
  description: Three ways to install agent skills today (the Claude Code marketplace, the npx skills CLI, and opencode's native skill tool) and what each delivers.
5
- tags: [agents, install]
5
+ tags: [agents, install, toolchain]
6
6
  status: stable
7
- generated: { by: claude-code/claude-opus-5-5, at: 2026-09-29T00:00:00Z }
8
- stale_after: 2027-03-29T00:00:00Z
7
+ stale_after: 2027-03-29
9
8
  sources:
10
9
  - id: claude-discover-plugins
11
10
  resource: https://code.claude.com/docs/en/discover-plugins
@@ -4,8 +4,7 @@ title: Installing skills with `npx skills`
4
4
  description: npx skills add installs a repository's skills into one or more agent paths, symlinked by default, with flags for agent, scope, skill selection, and list-only.
5
5
  tags: [agents, npx-skills]
6
6
  status: stable
7
- generated: { by: claude-code/claude-opus-5-5, at: 2026-09-29T00:00:00Z }
8
- stale_after: 2027-03-29T00:00:00Z
7
+ stale_after: 2027-03-29
9
8
  sources:
10
9
  - id: vercel-skills
11
10
  resource: https://github.com/vercel-labs/skills
@@ -4,8 +4,7 @@ title: Managing installed skills
4
4
  description: npx skills list, update, and remove, plus find, use, and init, as shown by the CLI help.
5
5
  tags: [agents, npx-skills]
6
6
  status: stable
7
- generated: { by: claude-code/claude-opus-5-5, at: 2026-09-29T00:00:00Z }
8
- stale_after: 2027-03-29T00:00:00Z
7
+ stale_after: 2027-03-29
9
8
  sources:
10
9
  - id: vercel-skills
11
10
  resource: https://github.com/vercel-labs/skills
@@ -4,8 +4,7 @@ title: opencode MCP configuration
4
4
  description: The mcp key for local and remote servers, the config file precedence list, and the opencode mcp commands.
5
5
  tags: [agents, opencode, mcp]
6
6
  status: stable
7
- generated: { by: claude-code/claude-opus-5-5, at: 2026-09-29T00:00:00Z }
8
- stale_after: 2027-03-29T00:00:00Z
7
+ stale_after: 2027-03-29
9
8
  sources:
10
9
  - id: opencode-mcp
11
10
  resource: https://opencode.ai/docs/mcp-servers/
@@ -4,7 +4,6 @@ title: opencode MCP server
4
4
  description: Configure opencode to load the conventional-git MCP server via uvx, with copy-ready config snippets.
5
5
  tags: [agents, opencode, mcp]
6
6
  status: stable
7
- generated: { by: claude-code/claude-opus-5-5, at: 2026-09-29T00:00:00Z }
8
7
  sources:
9
8
  - id: opencode-mcp
10
9
  resource: https://opencode.ai/docs/mcp-servers/
@@ -4,8 +4,7 @@ title: opencode skill discovery
4
4
  description: The project and global paths opencode reads skills from, the walk-up to the git worktree, and the name and description rules.
5
5
  tags: [agents, opencode]
6
6
  status: stable
7
- generated: { by: claude-code/claude-opus-5-5, at: 2026-09-29T00:00:00Z }
8
- stale_after: 2027-03-29T00:00:00Z
7
+ stale_after: 2027-03-29
9
8
  sources:
10
9
  - id: opencode-skills
11
10
  resource: https://opencode.ai/docs/skills/
@@ -4,8 +4,7 @@ title: opencode skill permissions
4
4
  description: permission.skill maps name patterns to allow, deny, or ask, and tools.skill false disables skills per agent.
5
5
  tags: [agents, opencode]
6
6
  status: stable
7
- generated: { by: claude-code/claude-opus-5-5, at: 2026-09-29T00:00:00Z }
8
- stale_after: 2027-03-29T00:00:00Z
7
+ stale_after: 2027-03-29
9
8
  sources:
10
9
  - id: opencode-skills
11
10
  resource: https://opencode.ai/docs/skills/
@@ -5,7 +5,6 @@ description: The marketplace, plugin, and skill names for this project, plus the
5
5
  resource: https://github.com/gajaguar/conventional-git
6
6
  tags: [agents]
7
7
  status: stable
8
- generated: { by: claude-code/claude-opus-5-5, at: 2026-09-29T00:00:00Z }
9
8
  sources:
10
9
  - id: claude-discover-plugins
11
10
  resource: https://code.claude.com/docs/en/discover-plugins
@@ -30,10 +29,12 @@ plugin, and skill names below match this repository's own
30
29
 
31
30
  ## Skills
32
31
 
33
- | Skill | Trigger phrasing |
34
- | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
35
- | `conventional-commit` | `commit`, `conventional commit`, `create a commit`, `commit changes` (outside a gitmoji context) |
36
- | `conventional-branch` | `create a branch`, `new branch`, `conventional branch`, `start working on`, `checkout a branch` (outside a ticket/module/team context) |
32
+ | Skill | Trigger phrasing |
33
+ | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
34
+ | `conventional-commit` | `commit`, `conventional commit`, `create a commit`, `commit changes` (outside a gitmoji context) |
35
+ | `conventional-branch` | `create a branch`, `new branch`, `conventional branch`, `start working on`, `checkout a branch` (outside a ticket/module/team context) |
36
+ | `conventional-suggest` | `suggest a commit message`, `what should this commit be`, `draft a commit from the diff`, `use jev for the commit` |
37
+ | `conventional-auth` | `set up the jev key`, `login to TypeSafe`, `configure OpenRouter`, `check my suggestion credentials`, `remove my API key` |
37
38
 
38
39
  ## Prerequisites
39
40
 
@@ -2,7 +2,7 @@
2
2
  type: rule
3
3
  title: No CLAUDE.md check
4
4
  description: make claude-md-check fails when a CLAUDE.md exists anywhere in the repository, because AGENTS.md is the only agent instructions file.
5
- tags: [agents]
5
+ tags: [agents, documentation, makefile]
6
6
  status: stable
7
7
  ---
8
8
 
@@ -2,7 +2,7 @@
2
2
  type: rule
3
3
  title: Help-line check
4
4
  description: make help-check fails when a Makefile target has no ## help line, so make help lists every target.
5
- tags: [makefile]
5
+ tags: [makefile, documentation]
6
6
  status: stable
7
7
  ---
8
8
 
@@ -7,7 +7,11 @@ Commit and branch naming.
7
7
  own hooks.
8
8
  * [Enforcing commits and branches](commits-check.md) - the pre-commit hook
9
9
  and `make commits-check` that enforce them.
10
+ * [Versioning, tags and releases](versioning.md) - SemVer bump criteria, which
11
+ bumps get a tag, and on-demand releases.
10
12
  * [Help-line check](help-check.md) - `make help-check` fails on a Makefile
11
13
  target without a `##` help line.
12
14
  * [No CLAUDE.md check](claude-md-check.md) - `make claude-md-check` fails
13
15
  when a `CLAUDE.md` exists, since `AGENTS.md` is the only agent file.
16
+ * [Tag vocabulary](tag-vocabulary.md) - the tags the notes carry and what
17
+ each one means.
@@ -0,0 +1,28 @@
1
+ ---
2
+ type: reference
3
+ title: Tag vocabulary
4
+ description: The tags the docs/ notes carry and what each one means, which docs-retag reads as its questions.
5
+ tags: [documentation]
6
+ status: stable
7
+ ---
8
+
9
+ # Tag vocabulary
10
+
11
+ Tags are cross-cutting: they name what a note is about, across directories. The
12
+ directory already names the topic. Every note here is about git, so `git` is not
13
+ a tag. The vocabulary is open: okflint accepts any tag, and a note may carry one
14
+ the table does not list, which `make docs-retag` never touches. A tag in the
15
+ table is one `make docs-retag` asks about, so add a row for each new tag worth
16
+ assigning that way.
17
+
18
+ A tag is lowercase and one word. Join words with a hyphen only when the
19
+ concept's own name has several words (a product, a tool or an established
20
+ term), and do not prefix a subtopic with its parent: `hooks`, not `git-hooks`.
21
+
22
+ | Tag | A note carries it when it… | A note does not when it… |
23
+ | :-------------- | :--------------------------------------------------------- | :------------------------------------------------------------- |
24
+ | `documentation` | is about how to write, structure or validate documentation | is about the product or the code rather than its documentation |
25
+ | `makefile` | is about a `make` target or the `Makefile` | does not concern the command surface |
26
+ | `release` | is about versions, tags that mark a release, or publishing | does not concern releasing |
27
+ | `toolchain` | is about which tool is installed, by whom and why | does not concern installing tools |
28
+ | `versioning` | is about SemVer and when to bump a version | does not concern version numbers |
@@ -0,0 +1,47 @@
1
+ ---
2
+ type: decision
3
+ title: Versioning, tags and releases
4
+ description: SemVer decides every version bump, a minor or major bump gets a Git tag, and publishing a release is on demand.
5
+ tags: [release, versioning]
6
+ status: stable
7
+ ---
8
+
9
+ # Versioning, tags and releases
10
+
11
+ The project follows [Semantic Versioning](https://semver.org/).
12
+
13
+ ## Choosing the bump
14
+
15
+ | Change | Bump |
16
+ | ----------------------------------------------------------------------------------- | ------- |
17
+ | Breaking change to the public contract (API, command surface, output, config keys) | major |
18
+ | Backwards-compatible feature | minor |
19
+ | Fix, or internal change a user can notice | patch |
20
+ | Documentation, CI, tests or development dependencies only | none |
21
+
22
+ Before `1.0.0` the contract is not frozen, so a breaking change bumps minor.
23
+ `1.0.0` is the release that declares the contract stable.
24
+
25
+ ## When the bump happens
26
+
27
+ - The pull request that introduces the change bumps the version, in its own
28
+ commit: `chore(release): set the version to X.Y.Z`.
29
+ - A pull request that needs no bump says so in its description.
30
+
31
+ ## Tags
32
+
33
+ - A minor or major bump gets an annotated tag `vX.Y.Z` on the merge commit of
34
+ the base branch, created after the merge and pushed to the remote:
35
+ `git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z`.
36
+ - A patch bump gets no tag. It is tagged only when someone asks to publish
37
+ that patch.
38
+ - Where the `Makefile` defines `make release-tag`, use it: it tags the base
39
+ branch as `v<project.version>` and pushes the tag, after checking that the
40
+ branch is clean and at its remote.
41
+
42
+ ## Releases
43
+
44
+ - A GitHub Release, and the package publication it triggers, happens on
45
+ demand. The agent MAY suggest one after tagging, and MUST NOT create it
46
+ unasked.
47
+ - The release is created from an existing tag.
@@ -13,5 +13,6 @@ with …` lines, and 🤖 markers as `commit.attribution` errors.
13
13
  `[commit] attribution_patterns` in `.conventional-git.toml` extends the
14
14
  defaults with case-insensitive regular expressions matched against each body
15
15
  line. Every front-end that calls `validate_message` enforces this by
16
- default; the default patterns cannot currently be disabled — see the
17
- README's Open items.
16
+ default. A repository that allows or requires such trailers sets
17
+ `[commit] disable_default_attribution_patterns = true` to skip the built-in
18
+ list; `attribution_patterns` still applies.
@@ -2,7 +2,7 @@
2
2
  type: reference
3
3
  title: Three enforcement surfaces
4
4
  description: The commit-msg, pre-commit, and pre-push hooks and what each one rejects.
5
- tags: [enforcement, git-hooks]
5
+ tags: [enforcement, hooks]
6
6
  status: stable
7
7
  ---
8
8
 
@@ -2,7 +2,7 @@
2
2
  type: tool
3
3
  title: Where hooks are installed
4
4
  description: The installer resolves Git's configured hooks path, so it handles linked worktrees and core.hooksPath destinations like husky.
5
- tags: [enforcement, git-hooks]
5
+ tags: [enforcement, hooks]
6
6
  status: stable
7
7
  ---
8
8