Dynamic metric

.agents/coding-conventions.md

@@ -0,0 +1,39 @@
+---
+last_updated: 2026-05-28
+---
+
+# Coding Conventions
+
+## 1. Language Choice
+
+- AutoMQ runtime code is Java-first.
+- New production classes should be Java unless they are tightly extending an
+  existing Scala-only Kafka integration surface.
+- Avoid adding new Scala runtime types for standalone AutoMQ behavior.
+- If a change touches an existing Scala class, keep the edit local and do not
+  migrate unrelated code just to satisfy the Java-first rule.
+
+## 2. Documentation
+
+- Code comments and Javadocs are written in English.
+- New public classes should have class docs that describe responsibility and
+  boundary.
+- New public methods should have method docs that describe behavior, inputs,
+  outputs, state changes, lifecycle effects, or failure semantics when relevant.
+- Avoid comments that only repeat the method or field name.
+
+## 3. Scope Control
+
+- Prefer existing Kafka/AutoMQ abstractions and module boundaries.
+- Do not introduce new dependencies when the JDK or existing project utilities
+  are enough.
+- For stateful runtime code, make ownership of lifecycle, concurrency, and
+  cleanup explicit in the API or class documentation.
+
+## 4. Kafka Fork Markers
+
+- When adding or changing AutoMQ logic inside an existing Kafka source file,
+  wrap the logic with `// AutoMQ inject start` and `// AutoMQ inject end`.
+- Do not add inject markers around import-only changes.
+- Keep marker ranges small so future Kafka upstream merges can identify the
+  AutoMQ-owned behavior.

.agents/review.md

@@ -0,0 +1,28 @@
+---
+last_updated: 2026-05-29
+---
+
+# Review Conventions
+
+## 1. Review Range
+
+- Review pull requests against the target branch full diff, such as
+  `origin/1.7...HEAD`.
+- Do not limit review to the latest commit unless the user explicitly asks for
+  an incremental review.
+
+## 2. Repository Rules
+
+- Check new production and test classes against the Java-first rule in
+  `coding-conventions.md` and `testing.md`.
+- Check new public class, public method, and test method docs against the
+  documentation rules in `coding-conventions.md` and `testing.md`.
+- Check AutoMQ changes inside existing Kafka source files for narrow
+  `// AutoMQ inject start` and `// AutoMQ inject end` markers.
+
+## 3. Verification
+
+- Before claiming an AutoMQ coding task is done, confirm the required local gate
+  from `testing.md` has passed.
+- Treat CI failures as review feedback: reproduce or inspect the failing gate,
+  fix the cause, and rerun the relevant local command before handing off.

.agents/testing.md

@@ -0,0 +1,59 @@
+---
+last_updated: 2026-05-29
+---
+
+# Testing Conventions
+
+## 1. Language Choice
+
+- New AutoMQ tests are Java-first.
+- Add Scala tests only when extending an existing Scala test class is clearly
+  lower-risk than creating a Java test.
+
+## 2. Test Documentation
+
+- Test method docs are written in English.
+- Each new test method should describe the scenario or contract being protected.
+- Prefer Given/When/Then wording for rule-heavy behavior and edge cases.
+- Avoid comments that only restate the test method name.
+
+## 3. Tagged Test Selection
+
+- AutoMQ CI commonly runs tagged test tasks instead of every Gradle test task.
+- New focused AutoMQ unit tests should be tagged with `@Tag("S3Unit")` when
+  they are expected to run in the tagged S3Unit selection.
+- When verifying AutoMQ changes locally, prefer the workflow-style tagged
+  selection when the change is broad enough:
+
+```bash
+./gradlew --build-cache metadata:S3UnitTest core:S3UnitTest s3stream:test
+```
+
+- For narrow changes, run focused `core:S3UnitTest --tests ...` first, then
+  broaden to the workflow-style selection before handing off.
+- When adding E2E coverage, include the test in the appropriate
+  `tests/suites/automq_test_suite*.yml` suite so the CI selection can discover
+  it.
+
+## 4. Required Completion Gate
+
+- Before claiming an AutoMQ coding task is done, run the CI-style formatting,
+  license, and checkstyle gate:
+
+```bash
+./gradlew --build-cache rat checkstyleMain checkstyleTest spotlessJavaCheck
+```
+
+- Do not replace this gate with focused unit tests. Run it in addition to the
+  relevant focused or tagged test selection for the change.
+
+## 5. Checkstyle Suppression
+
+- Use narrow `@SuppressWarnings` only when the rule conflicts with a deliberate
+  structure, such as enum-switch hot-path classification, schema dispatch, or a
+  test class that must cover many generated protocol data types together.
+- Prefer fixing ordinary style issues, unused imports, missing locale, and
+  low-cost complexity reductions instead of suppressing them.
+- When suppressing a Checkstyle rule in code, keep the annotation at the
+  smallest practical scope and include the `checkstyle:` prefix when suppressing
+  a specific method-level Checkstyle rule.

.github/workflows/build.yml

@@ -21,11 +21,29 @@ on:
     branches: [ "main" ]
 
 jobs:
+  changes:
+    runs-on: ubuntu-latest
+    outputs:
+      build: ${{ steps.filter.outputs.build }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            build:
+              - '**'
+              - '!.agents/**'
+              - '!**/*.md'
+              - '!docs/**'
+              - '!specs/**'
   build-automq:
+    needs: [ changes ]
+    if: ${{ needs.changes.outputs.build == 'true' }}
     uses: ./.github/workflows/build_automq.yml
   build-result:
     runs-on: ubuntu-latest
-    needs: [ build-automq ]
+    needs: [ changes, build-automq ]
     if: ${{ always() }}
     steps:
       - uses: actions/checkout@v4