# Dependency notes for Java and Kotlin

A `pom.xml` or a Gradle build file says which version of a library a service uses. It does not say that the Jackson modules have to move together, that the service is held on an older line until a migration lands, or which integration tests show an upgrade is safe. An XML comment or a `//` line has room for a phrase, not for that history.

Pacmon keeps a note for each dependency beside its build file — `.pacmon/maven/DEPENDENCY-NOTES.md` for Maven, `.pacmon/gradle/DEPENDENCY-NOTES.md` for Gradle — and shows it on the dependency in the editor. Gradle builds in the Groovy and the Kotlin DSL are both read.

## What Pacmon reads

### Maven

- **Manifest:** `pom.xml`
- **Notes file:** `.pacmon/maven/DEPENDENCY-NOTES.md`
- **Section heading:** `groupId:artifactId`: `## org.slf4j:slf4j-api`

Pacmon reads the `<dependencies>` of the project and its profiles, not `<dependencyManagement>` or plugin dependencies. Parent POMs are not read.

### Gradle

- **Manifest:** `build.gradle`, `build.gradle.kts`
- **Notes file:** `.pacmon/gradle/DEPENDENCY-NOTES.md`
- **Section heading:** `group:name` or the catalog alias: `## org.slf4j:slf4j-api`, `## libs.junit.jupiter`

Pacmon reads module coordinates and `libs.*` aliases in a `dependencies` block, not plugins, constraints, `project(…)`, `files(…)` or catalog bundles. The script is never run, so a dependency added by code is not seen.

Pacmon never runs Maven or Gradle, and it does not resolve parent POMs, BOMs or `libs.versions.toml`. A note belongs to the dependency as the build file writes it.

## Example

```xml
<dependencies>
  <dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.18.2</version>
  </dependency>
  <dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-jsr310</artifactId>
    <version>2.18.2</version>
  </dependency>
</dependencies>
```

`.pacmon/maven/DEPENDENCY-NOTES.md`:

```md
## com.fasterxml.jackson.core:jackson-databind

JSON for the REST API and the Kafka payloads. Upgrade every Jackson artifact together.

### Agent notes

- purpose: JSON mapping for the REST API and the Kafka message payloads
- bump-with: com.fasterxml.jackson.datatype:jackson-datatype-jsr310
- verify: `mvn -pl api test` and the contract tests (`mvn -Pcontract verify`)
- verified: 2.18.2
```

In a Gradle build, a version-catalog alias is a note key of its own:

```kotlin
dependencies {
    implementation("org.slf4j:slf4j-api:2.0.16")
    testImplementation(libs.junit.jupiter)
}
```

Its sections in `.pacmon/gradle/DEPENDENCY-NOTES.md` are `## libs.junit.jupiter` and `## org.slf4j:slf4j-api`.

## For AI coding agents

An agent reads a dependency's section before it adds, upgrades or removes it. `bump-with:` lists the artifacts that have to move with it, and `verify:` the Maven or Gradle tasks to run afterwards. See [the rules agents follow](https://pacmon.dev/agents/).