---

inclusion: always

Git Conventions

This project uses Git for version control. Follow these conventions for all commits and branches.

Conventional Commits

All commit messages must follow the Conventional Commits specification (https://www.conventionalcommits.org/).

Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

| Type | Purpose | |------------|---------------------------------------------------------| | `feat` | A new feature or capability | | `fix` | A bug fix | | `refactor` | Code change that neither fixes a bug nor adds a feature | | `test` | Adding or updating tests | | `docs` | Documentation changes | | `chore` | Build process, tooling, or auxiliary changes | | `ci` | CI/CD configuration changes | | `perf` | Performance improvement | | `style` | Code style changes (formatting, whitespace) |

Scopes

Use a scope to indicate the area affected. Common scopes for this project:

* `lexer` — lexer recognition changes * `parser` — Menhir grammar changes * `ast` — AST type definitions * `normalize` — normalization phase * `inline` — inline parsing * `prescan` — pre-scan configuration discovery * `diagnostic` — diagnostic reporting * `test` — test infrastructure (not individual test additions)

Omit the scope when the change is cross-cutting or does not fit a single module.

Rules

* Use the imperative mood in the description: "add heading parser", not "added heading parser". * Keep the first line under 72 characters. * Do not end the description with a period. * Use the body to explain *what* and *why*, not *how*. * Use `BREAKING CHANGE:` in the footer when a change breaks the public API. * A `!` after the type/scope indicates a breaking change: `feat(ast)!: restructure heading representation`.

Examples

feat(lexer): add keyword line classification

Recognize lines matching #+KEY: VALUE as Keyword tokens.

fix(normalize): attach affiliated keywords across blank lines

Previously affiliated keywords separated by a blank line from their
target element were left as standalone nodes. Now they correctly
remain unattached per the Org spec.

test: add malformed block recovery fixtures

refactor(parser): extract list item grouping into helper function

Conventional Branches

Branch naming format

<type>/<short-description>

Use kebab-case for the description. Keep it concise but descriptive.

Branch types

| Prefix | Purpose | |-------------|----------------------------------------------------| | `feat/` | Feature development | | `fix/` | Bug fixes | | `refactor/` | Refactoring without behavior change | | `test/` | Test additions or infrastructure | | `docs/` | Documentation work | | `chore/` | Tooling, build, or maintenance |

Rules

* Branch from `master` unless working on a dependent feature. * One logical change per branch. * Do not reuse branch names after merging. * Delete branches after they are merged.

Examples

feat/heading-parser
fix/list-indentation-edge-case
refactor/inline-lexer-modes
test/block-recovery-fixtures
docs/update-support-matrix
chore/upgrade-menhir

General Git practices

* Keep commits atomic: one logical change per commit. * Commit after each individual feature is implemented. * Do not mix formatting changes with behavioral changes in the same commit. * Prefer rebase workflows to keep linear history on `master`. * Squash fixup commits before merging to `master`. * Do not commit generated files (build artifacts, `.merlin`, etc.). * Do not commit editor-specific files unless shared tooling requires them. * Always amend the latest unpushed commit when the requested modifications concern files already modified in that commit. Otherwise, create a new commit.

Pre-commit checks

Before every commit, run the following in order:

1. `opam exec -- dune fmt` — format all OCaml source files with ocamlformat.
2. `opam exec -- dune build` — verify compilation succeeds.
3. `opam exec -- dune runtest` — verify all tests pass.

Do not commit if any of these steps fail.

Authorship

When an AI agent produces code, authorship must be correctly attributed in the commit metadata.

* **Author**: the AI agent that produced the changes. Use the format:

  Agent-Name (effort-level) <noreply@company-domain>

Where `effort-level` reflects the reasoning or effort mode the agent was operating under when it produced the changes (e.g. `high`, `medium`, `standard`, or a model-specific indicator). The email domain identifies the company developing the agent.

Example: `Kiro (high) <noreply@kiro.dev>`

* **Committer**: always the human who reviewed and accepted the changes. Use the human's normal Git identity.

Set authorship with:

git commit --author="Kiro (high) <noreply@kiro.dev>" -m "..."

This ensures `git log` and `git blame` clearly distinguish AI-generated code from human-written code, while the committer field records who took responsibility for merging it.