AGENTS.md · git:20261115.6d423ff · 2026-11-15 · sha256 073fdb6b80bf7558

AGENTS.md git:20261115.6d423ffA

Immutable. This exact content never changes and is served at /api/v1/blob/073fdb6b80bf7558.

# VibeTags — Agent Instructions

Start with [llms.txt](llms.txt) for a map of this repo's docs and layout.

The primary agent briefing is [CLAUDE.md](CLAUDE.md) — build commands, build
order, architecture invariants, and the `<project_guardrails>` block (locked
files, contract-frozen signatures, hot-path constraints). It is tool-neutral
despite the name: read and follow it whichever agent you are.

Ground rules for any agent working here:

- Respect the guardrails in CLAUDE.md: never edit files/elements listed as
  locked, never change contract-frozen signatures.
- Never hand-edit content between `VIBETAGS-START`/`VIBETAGS-END` markers in
  any file — it is generated by this project's own annotation processor.
- Build order matters: `vibetags-annotations` → `vibetags` → `vibetags-bom`
  → `example`. Always build from the subproject's own directory.
- Reference docs load on demand: `docs/ANNOTATIONS.md` (annotation reference),
  `docs/PLATFORMS.md` (output-file table), `docs/TESTS.md` (test coverage map),
  `docs/ARCHITECTURE.md` (deep dive), `docs/DEPENDENCIES.md` (third-party artifacts).

Note: this file is intentionally not VibeTags-managed — other AI config files
exist at the root, so the processor's AGENTS.md sole-file fallback leaves it
untouched.

<!-- VIBETAGS-START -->
# AUTO-GENERATED AI RULES
# Generated by VibeTags | https://github.com/PIsberg/vibetags
# Do not edit manually.

## LOCKED FILES (DO NOT EDIT)
- **se.deversity.vibetags.processor.AIGuardrailProcessor.generateFiles()**: Step order is load-bearing: fingerprint check → sidecar write → sidecar read → merge → file write → cache flush; reordering steps silently skips regeneration or corrupts multi-module output
- **se.deversity.vibetags.processor.internal.TransitiveManifest.RESOURCE_PACKAGE**: Must stay a valid Java package name. javac's CLASS_PATH location skips archive directories that are not package identifiers, so moving these manifests under META-INF/ leaves Filer.getResource listing zero entries and transitive discovery fails silently while the conventional location looks correct. TransitiveManifestPathTest pins the working path.
- **se.deversity.vibetags.processor.model.GuardrailAnnotations.ALL**: Append only. This order fixes the insertion order of every LinkedHashSet downstream, so reordering or removing an entry rewrites generated files in every consuming build, with nothing failing to name the cause. BuildFingerprint hashes in its own separately pinned order; the two are not the same list and must not be aligned.

## CONTEXTUAL RULES
- `se.deversity.vibetags.processor.AIGuardrailProcessor.earlyExitAllowed()`: Focus on A step added after the collection walk that reads the collected model must also turn the early exit off here. Avoid Adding such a step without a clause here: a no-op rebuild then skips it with nothing reporting it (#834).
- `se.deversity.vibetags.processor.AIGuardrailProcessor.finishUnchangedBuild()`: Focus on Every diagnostic generateFiles() raises before its fingerprint short-circuit must also be raised here. Avoid Adding one there without a call here: a no-op rebuild that takes the early exit drops it in silence (#859).
- `se.deversity.vibetags.processor.AIGuardrailProcessor.warnAboutPartialMerges(java.util.Set<java.lang.String>,java.util.Map<java.lang.String,java.nio.file.Path>,java.util.List<se.deversity.vibetags.processor.internal.ModuleSidecar>)`: Focus on Every warning hosted here describes state still on disk: warnAboutMergeState raises it again on a rebuild that changes nothing. Avoid Hosting a warning about the write just made here: a no-op rebuild would repeat it on every build (#1063).
- `se.deversity.vibetags.processor.internal.AnnotationCollector`: Focus on Accumulates annotated elements across multiple javac processing rounds, then snapshots them into a compiler-free GuardrailModel. Ordering is settled in GuardrailModel, which sorts every bucket by TaggedElement.path() — javac's getElementsAnnotatedWith has no specified iteration order, so anything that preserves it makes generated output depend on which machine compiled it. Avoid Restoring javac's iteration order as the output order, here or in GuardrailModel — it differs between Maven and Gradle and between machines, which churns committed guardrail files and misses the write cache. OutputOrderDeterminismTest pins it.
- `se.deversity.vibetags.processor.internal.EnforcementBaseline`: Focus on Consumers commit .vibetags-baseline, so a new format must keep reading format 1. Avoid Changing FORMAT_MARKER alone: exists() then reports the committed baseline as absent, and GuardrailEnforcer answers that with a warning and a pass, so enforcement switches off on upgrade with green builds.
- `se.deversity.vibetags.processor.internal.GranularRulesWriter`: Focus on Writes granular rule files (per-class, or role-grouped when .vibetags-roles is present) for Cursor, Windsurf, Trae, Roo, and similar platforms; cleanup runs AFTER write to avoid delete-then-recreate cycles. Avoid Running cleanup before write — would delete files that are about to be recreated, causing spurious filesystem events and empty windows for incremental build tools.
- `se.deversity.vibetags.processor.internal.ServiceRegistry`: Focus on Maps platform service keys to output file paths; resolves active services by checking file existence on disk. Avoid Creating output files that do not already exist — file presence on disk is the user's explicit opt-in signal.
- `se.deversity.vibetags.processor.internal.SourceDigest`: Focus on Every input that shapes generated output and is not an -A option, an opt-in file or a .vibetags-* config must be hashed here. Avoid Dropping or missing an input: a no-op rebuild then keeps stale output, and a test that compiles once never reaches the early exit, so nothing fails.
- `se.deversity.vibetags.processor.internal.TomlValueSpans`: Focus on The span body is annotation text, dependency JARs' included, spliced into a PR-Agent config the user owns: keep it Escape.tomlMultiline-encoded and marker-defused. Avoid Splicing raw text: a dependency could close the string and add review settings, or end the span early so the value grows a copy of itself on every build.
- `se.deversity.vibetags.processor.internal.TransitiveManifest`: Focus on Manifests are read out of JARs already on Maven Central by other processor versions, so a field renamed or redefined needs a FORMAT_VERSION bump. Avoid Changing the JSON shape in place: older consumers misread it as version 1. A bump has a cost too: older processors skip the manifest and drop its inherited rules.

## 🧠 CORE FUNCTIONALITY
The following elements are well-tested core components. Make changes with extreme caution.

- **se.deversity.vibetags.processor.AIGuardrailProcessor** (sensitivity: critical): Runs inside every consumer's javac: process() turns a RuntimeException into a WARNING (an ERROR in check mode), and anything escaping that catch fails their build
- **se.deversity.vibetags.processor.internal.GuardrailFileWriter** (sensitivity: high): Invariant 2 lives here: hand-authored content outside VIBETAGS-START/END must never be overwritten or lost
- **se.deversity.vibetags.processor.internal.ModuleSidecar** (sensitivity: high): The .vibetags-mod-* format is read by modules compiled separately, possibly by another processor version; changing it breaks them
- **se.deversity.vibetags.processor.internal.PartialRoundDetector** (sensitivity: high): Both conditions in unreadAnnotatedSources are load-bearing and neither may be dropped as redundant: without the missing-element check an excluded-but-annotated source stops VibeTags writing for good, and without the unread-source check a genuinely deleted annotation can never have its rule file retired
- **se.deversity.vibetags.processor.internal.WriteCache** (sensitivity: high): A false positive, stale output taken as unchanged, silently leaves generated files wrong

## ⚡ PERFORMANCE CONSTRAINTS
Hot-path elements — never introduce O(n²) or worse. Always reason about complexity before proposing changes.

- **se.deversity.vibetags.processor.internal.BuildFingerprint.fingerprint(java.lang.String)**: O(N) in string length; uses String.hashCode() which HotSpot intrinsifies on x86; must not allocate intermediate byte[]
- **se.deversity.vibetags.processor.internal.WriteCache.isUnchanged(java.nio.file.Path,java.lang.String)**: O(1): one stat(2) syscall plus one 8-char string compare; must not allocate byte[] — the prior CRC32C implementation did and was removed for this reason

## 🔐 CONTRACT-FROZEN SIGNATURES
Internal logic may be modified, but never change method names, parameter types, parameter order, return types, or checked exceptions.

- **se.deversity.vibetags.processor.AIGuardrailProcessor.process(java.util.Set<? extends javax.lang.model.element.TypeElement>,javax.annotation.processing.RoundEnvironment)**: JSR 269 contract: must return false so peer annotation processors can claim the same annotations; return type is fixed by AbstractProcessor
- **se.deversity.vibetags.processor.internal.BuildFingerprint.compute(se.deversity.vibetags.processor.internal.AnnotationCollector,java.util.Set<java.lang.String>)**: Same inputs must always produce the same 8-hex output across JVM restarts; changing the algorithm silently invalidates all existing .vibetags-cache files
- **se.deversity.vibetags.processor.internal.GuardrailFileWriter.writeFileIfChanged(java.lang.String,java.lang.String,boolean)**: Public API since v0.1; tests and the processor both bind to the (String path, String content, boolean hasNewRules) signature and return semantics
- **se.deversity.vibetags.processor.internal.ModuleSidecar.mergeFor(java.lang.String,java.util.List<se.deversity.vibetags.processor.internal.ModuleSidecar>,boolean)**: Sub-marker format constants (SUB_MARKER_*_FORMAT) are embedded in generated CLAUDE.md and .cursorrules; changing them silently corrupts multi-module merged output on the next compile

## 🧪 TEST-DRIVEN REQUIREMENTS
Changes to the following elements MUST be accompanied by a matching test update in the same response.

- **se.deversity.vibetags.processor.AIGuardrailProcessor**: Coverage goal: 90%. Framework: JUNIT_5. Mock policy: Write the failing test first, against the real javac through ProcessorTestHarness; Mockito only where a ProcessingEnvironment cannot be real.
- **se.deversity.vibetags.processor.internal.GuardrailFileWriter**: Coverage goal: 90%. Framework: JUNIT_5. Mock policy: Write the failing test first; marker preservation is asserted on real files with hand content around the block, never on string fixtures alone.
- **se.deversity.vibetags.processor.internal.ModuleSidecar**: Coverage goal: 90%. Framework: JUNIT_5. Mock policy: Write the failing test first; the sidecar format is cross-module law, so tests read and write real .vibetags-mod-* files, never mocks of them.
- **se.deversity.vibetags.processor.internal.WriteCache**: Coverage goal: 90%. Framework: JUNIT_5. Mock policy: Write the failing test first; drive real files in a temp dir, never a mocked filesystem (a false cache positive silently corrupts output).

## 🧵 THREAD-SAFE BY DESIGN
These elements are explicitly designed to be thread-safe. Preserve the synchronization invariant on every change.

- **se.deversity.vibetags.processor.VibeTagsLogger**: Strategy: THREAD_LOCAL. Note: Logback loggers are partitioned by root and by compiling thread, so parallel compilations, two modules sharing one root included, never detach each other's appenders (VibeTagsLoggerAsyncTest and VibeTagsLoggerConcurrencyTest prove it)
- **se.deversity.vibetags.processor.internal.EnforcementBaseline**: Strategy: SYNCHRONIZED. Note: update() alone is safe, and across processes as well as threads: a per-root monitor plus an exclusive lock on .vibetags-baseline.lock serialise the re-read and rename that a parallel reactor's modules run against one shared file. The read side is an unguarded snapshot on purpose
- **se.deversity.vibetags.processor.internal.GuardrailFileWriter**: Strategy: IMMUTABLE. Note: Stateless aside from injected Messager/Logger references; every write is an atomic temp-file replace, so the parallel write phase never interleaves partial content (GuardrailFileWriterAsyncTest proves it)
- **se.deversity.vibetags.processor.internal.ModuleSidecar**: Strategy: OTHER. Note: Atomic temp-file moves (ATOMIC_MOVE with plain-move fallback); concurrent saves and reads never tear a sidecar or prune a sibling's (ModuleSidecarAsyncTest proves it)
- **se.deversity.vibetags.processor.internal.WriteCache**: Strategy: SYNCHRONIZED. Note: Safe for concurrent calls on one instance (WriteCacheAsyncTest proves it). Instances over one .vibetags-cache, one per module of a parallel reactor, merge on flush, so a sibling's entries survive. The merge is not a lock: a reactor module must flush under the generation lock, or two flushes can drop one side's changes, a cleared source digest among them. They never vouch for another writer's bytes (WriteCacheCrossInstanceAsyncTest proves it)
- **se.deversity.vibetags.processor.internal.validation.ValidationRule**: Strategy: IMMUTABLE. Note: Implementations must hold no state. ValidationRules keeps one instance per rule for the life of the JVM, and a Gradle daemon runs that instance against many unrelated compilations in sequence, so a field added here carries one project's elements into another project's diagnostics. Everything a check needs arrives as the ValidationContext and Element arguments.

## ❄️ IMMUTABLE TYPES
The following types are immutable. Do not introduce non-final fields, setters, or mutating methods.

- **se.deversity.vibetags.processor.internal.BuildFingerprint**: Purely stateless; private constructor prevents instantiation; all computation results are returned as values

## 🏛️ ARCHITECTURAL BOUNDARY CONSTRAINTS
Strict layering must be respected. No illegal boundary crossing references:

- **se.deversity.vibetags.processor.internal.content**: Belongs to layer: `rendering`. Prohibited from referencing: [javax.lang.model, javax.annotation.processing, javax.tools, com.sun.source, se.deversity.vibetags.processor.internal]
- **se.deversity.vibetags.processor.model**: Belongs to layer: `model`. Prohibited from referencing: [javax.lang.model, javax.annotation.processing, javax.tools, com.sun.source, se.deversity.vibetags.processor, se.deversity.vibetags.processor.internal]

## 🔐 SECURITY-CRITICAL CODE
Do not weaken security properties of these elements. Review every change for security impact:

- **se.deversity.vibetags.processor.internal.JsonValueSpans**: Security-critical code [Splices annotation text, including attributes copied out of third-party dependency JARs, into greptile.json and .greptile/config.json, review configurations the user owns. The span body must stay Escape.json-encoded and marker-defused: without the first a dependency can close the string and add settings such as skipReview, and without the second it can end the span early so the value grows a copy of itself on every build.]. Do not weaken security properties. Flag any change for security review.
- **se.deversity.vibetags.processor.internal.TransitiveManifestReader**: Security-critical code [Trust boundary. Manifests read here are authored by third-party dependency JARs, and their rules are merged into the consumer's always-loaded instruction files, so a dependency can put text in front of the consumer's agent. Treat every value as untrusted input: keep the MAX_LOOKUPS cap and the SKIPPED_PREFIXES list, and route interpolation through Escape rather than widening what a manifest may contain.]. Do not weaken security properties. Flag any change for security review.
- **se.deversity.vibetags.processor.internal.content.Escape**: Security-critical code [Output encoding for the generated instruction files. Every interpolated value reaches an aggregate through here, including annotation attributes copied verbatim out of third-party dependency JARs; a weakened method lets that text close a tag and forge its own <locked_files> or <rule> entries in a file the agent loads on every session.]. Do not weaken security properties. Flag any change for security review.
- **se.deversity.vibetags.processor.internal.TransitiveManifestReaderLimitsTest**: Security-critical code [Pins the MAX_LOOKUPS cap and the SKIPPED_PREFIXES list of TransitiveManifestReader; relaxing a case to make it pass widens what a dependency may put in front of an agent]. Do not weaken security properties. Flag any change for security review.

## 🧩 LOAD-BEARING ODDITIES
These look wrong, redundant, or over-defensive and are deliberate. Refactoring is allowed only while the stated invariant survives.

- **se.deversity.vibetags.processor.internal.JsonValueSpans**: Looks removable but is deliberate. Invariant: Edits are offsets spliced into the original text; the document is validated with Json but never parsed and re-serialised. Breaks if changed: Re-serialising rewrites key order, whitespace, number spelling and the user's own escape sequences in a file VibeTags does not own, on every build, with nothing failing except the byte-preservation cases in JsonValueSpansTest and GreptileEndToEndTest.
- **se.deversity.vibetags.processor.internal.content.PlatformRenderer**: Looks removable but is deliberate. Invariant: A renderer whose output is YAML declares mergeShape(); a renderer whose marker-free output varies per module declares wholeFileMerge(). The defaults return null, which means plain concatenation. Breaks if changed: Silent data loss across a reactor. Concatenated YAML repeats a top-level key, so the parse either fails or keeps only the last module; a marker-free file is a whole-file overwrite, so it ends up holding one module's view of the whole project. Neither shows up in a single-module build, which is where a new renderer gets tested.

Guardrails for test code are in TESTING.md. Read it before modifying anything under a test source set.
<!-- VIBETAGS-END -->