Repository navigation
VibeTags v1.4.3
[1.4.3] - 2026-11-21
Upgrade note: no generated file moves, but a build that opts into llms-full.txt gets a new
warning. The consumer sweep built five downstream repositories at 1.4.3. codekarta, skill3 and
blindbean generated the same files byte for byte as the same builds at 1.4.2; async-test-lib's only
change is the ~roots= sidecar line 1.4.2 introduced, and common-license-lib's files did not move.
A build that opts into llms-full.txt now prints one compiler WARNING, which fails a build compiled
with -Werror (see Deprecated). A module that sets -Avibetags.module and mirrors into a target
writes its mirrored rule files under the new name, and the old ones need deleting by hand (#1076,
under Fixed).
Changed
-
CI builds on JDK 27 (#1117). The Maven and Gradle jobs' matrices are now 21, 25, 26 and 27;
JDK 27 is the current release. Measured locally on Temurin 27.0.1 before adding the legs: the
annotations module verifies, the processor's fast tier passes (3,347 tests, Error Prone and
NullAway included), and Gradle 9.9.1 builds both modules. -
AIGuardrailProcessorspells diagnostic paths throughPathStrings(internal; no output changes,
#1101). Five of its six hand-written.replace('\\', '/')conversions now call
PathStrings.relativeorPathStrings.forwardSlashes. The sixth is inside the@AILocked
generateFiles()and stays until the owner approves an edit there. Mutating each site first
showed three of the five were tested by nothing, soDiagnosticPathSeparatorTest(the
opted-in-after and module-id-collision warnings) and aPartialRoundGuardrailLossTestcase pin
them; each fails on Windows when its site's conversion is removed. The new import moves the
locked range in.vibetags-locksby one line, to 1254-1569. -
GuardrailFileWriter.writeContentWithBackupisstageAndMove(internal; no output changes,
#1109). It stages content in a temp file beside the target and moves it into place, and never
made a backup, so the name described something it did not do. The two hand-written PlantUML
diagrams anddocs/architecture/design-decisions.mdfollow; the code-karta diagrams show no
structural change. -
The release steps count the organization's month on Maven Central, not this repository's tags
(#863). Central's limits (7 releases, 1,167 files, 78 MB a month) are per organization, and
async-test-lib and every other group underse.deversitydraw on them too, so the tag count in
docs/RELEASING.mdstep 0c and the release skill's step 1b missed most of the usage: on
2026-11-17 it showed 1 release for November where the organization had 4 and 534 of its 1,167
files. The new.github/scripts/central-month-usage.shreads repo1's public directory listings,
counts one release per group and version published that month, sums their files and bytes, and
exits 1 once a limit is reached and 2 when repo1 cannot be read (never zero). A version published in
several deployments counts once per deployment (#1111, below), so October 2026 reads 11, as
Central counted it. Both release steps run it; the cadence of at most 3 vibetags releases a month stays.
central-month-usage.test.shruns it against fixture listings inbuild.yml's Central Bundle
Shape job, andCentralPublishingBudgetTestfails if either release step or that CI step stops
running it. The test was written first and failed for each. -
The
modelpackage holds data only (internal; no output changes). Logic that lived in the
compiler-free model moves to the layer that uses it, one commit per class, each behind tests
written first and shown red against a mutant of the behaviour they pin.RoleConfig, which
reads.vibetags-roles, compiles its globs and memoises matches, is a service rather than data
and now lives inprocessor.internal.content, as doesContentHash, the fingerprint hash
function.TaggedElement.ownsSourceFile()becomesElementFiles.ownsSourceFile(element)beside
the formatters that call it, and the element's file-name defaults are resolved in its builder,
so its constructor only assigns.ElementTagkeeps its constants only:fromName,isClassand
isInterfacebecome static methods onElementKinds.GuardrailModel's derived views
(safetyOnly,withoutSafety,excluding,labeledSets) becomeGuardrailModelViewsin
processor.internal. The builder that sorts and derives a model becomesGuardrailModelBuilder,
andGuardrailModelkeeps fields and accessors only; anArchitectureRulesTestrule lets no
other class call its constructor, so no model can skip the sort that keeps generated output
identical on every machine.TransitiveRuleis no longerComparable: its attribute summary
and sort order becomeTransitiveRules.memberSummaryandTransitiveRules.ORDER.
GuardrailAnnotations.labelbecomesAnnotationLabels.label, leaving the registry as constants.
Generated files are unaffected. -
GuardrailModelBuilder.BY_IDENTITYis@AILocked(internal). The comparator fixes the order
of every bucket, so a change to it rewrites every consuming build's generated files and fingerprint
with nothing failing to name the cause. Its lock entry is always loaded, so the budget
ProjectFactsConsistencyTestholds this repository's ownCLAUDE.mdblock to rises from 7,000 to
7,300 bytes; the block is 7,296. -
PlatformRendererRegistry's four service-key lookups share one helper (internal; no output
changes).mergeShapeFor,sourceSetMergeFor,filePrologueForandwholeFileMergeFor
each repeated the same key-to-platform-to-renderer resolution with its own null checks; they now
call one privaterendererFor(serviceKey).PlatformRendererRegistryServiceKeyTest, written
first and green on the old code, pins that each lookup returns what the platform's renderer
declares for all 61 platforms and answers nothing forroot_index, an unknown key and"".
Three deliberate breakages of the new code (a droppedsourceSetMerge, a non-empty prologue for
an unknown key, the helper resolving the wrong platform) failed 26, 3 and 60 of its 64 cases. -
ReactorRootDetector.findReactorRootAbovereturnsOptional<Path>instead of a nullable
Path(internal; no output changes). Its one caller, the #296 detached-module warning in
AIGuardrailProcessor, no longer null-checks: it hands the root to a newwarnDetachedFrom
throughifPresent. The privaterelativisehelper returnsOptional<String>the same way.
A newDetachedModuleWarningTestcase, written first and green on the old code, pins the module
name (group/module-core, forward slashes) and the-Avibetags.root=value the warning prints for
a nested module. Two deliberate breakages of the new code failed it: the detector answering the
module's parent instead of the declaring reactor (3 failures), and the module name keeping
Windows backslashes (1). -
Mirror discovery and the sibling-module search share one directory walk that returns its result
(internal; no output changes).MirrorConfig.collectandMirrorWriter.collectModuleswere two
copies of the same bounded, sorted, depth-first walk, each filling a list passed in by its caller.
Both now useMirrorConfig.directoriesBelow(dir, levels), which returns the directories, and
filter the result. Theseen-set cycle guard is gone: every path in the walk is its parent plus one
name, so the set never matched, and the depth bound is what stops a symlink cycle. New tests pin
discovery order (depth-first, siblings sorted) and the sibling search's limits (three levels, own
build file,target/andsrc/skipped); they passed before the change. Breaking the new walk
failed them: breadth-first order (1 failure), one level short (3), and counting directories with no
build file of their own as modules (4). -
Json's character tests are named predicates (internal; no output changes). The parser for
transitive manifests compared characters inline:c == ' ' || c == '\t' || ...for whitespace and a
six-way test for number characters. They are nowisJsonWhitespace,isNumberChar,
isExponentMarkerandisSign, each saying why it is not theCharactermethod it resembles.
NewJsonTestcases, green before the change, pin RFC 8259's ASCII-only sets: form feed, vertical
tab, no-break and Unicode spaces are not whitespace, and non-ASCII decimal digits are not digits.
Swapping inCharacter.isWhitespacefailed 4 of them andCharacter.isDigit3, so the tempting
"simplification" cannot widen what a third-party JAR's manifest may contain unnoticed. -
Two hand-kept agreements are now enforced by the code (internal; no output changes).
GuardrailEnforcerheld its guarded elements twice, as a map of signatures and a map of elements
"filled in lockstep", with an unreachable null branch guarding their agreement; it now keeps the
elements only and reads each one's own signature.MirrorWriter's sibling search depth was the
literal 3, documented as "one level past mirror discovery"; it is nowMirrorConfig.MAX_DEPTH + 1
(Clean Code G22, make logical dependencies physical). Six new tests, green before the change, pin
the enforcer's report order, an element in two families, constructor naming and the mirror depth
relation; breaking the one-map version failed 2 to 18 of the enforcer tests, and raising the
discovery depth now fails the sibling search's depth test as well. -
MethodBodyGuardrailScanner.topLevelasks one named question (internal; no output changes). Its
loop condition readcurrent.getEnclosingElement().getKind()four times in one boolean (Clean Code
G36, G28). It is nowwhile (isNested(current)), withisNestedreading the enclosing element's
kind once.MethodBodyGuardrailScannerTopLevelTest, 59 cases written first and green on the old
loop, pins where the walk lands for real javac elements of every nesting shape and for every
ElementKindconstant of the running JDK; five breakages of the new predicate failed 3 to 45 of
them each. -
Enforcement families are an enum,
GuardrailEnforcer.Family(internal). They were bare strings:
"locked","contract"and"publicapi"asMapkeys,Set<String>throughparseFamilies,
enforceand the processor (Clean Code J3, enums over constant groups). Each constant now carries
its key and its annotation, so the "unknown family, unreachable" branch is gone, and strings remain
only where they are a format: the option a user writes and.vibetags-baseline's family column.
One observable difference:-Avibetags.enforce=allused to add the families inMap.of's
iteration order, which the JDK leaves unspecified, so thefamilies=field ofenforce.resultcould
list them in any order; it is now always[locked, contract, publicapi]. Every other message, the
baseline file and the log fields are unchanged.GuardrailEnforcerFamiliesTest, 41 cases written
first and green on the strings, compares families by name; renaming one key failed 24 of the
enforcer tests,toStringreturning the constant name 19, sorting by declaration order 13,all
selecting two families 8, and swapping two families' annotations 9. -
LlmsRendererrenders from a table of sections (internal; no output changes). Itsrender
was 44 hand-writtenappendSectioncalls, each re-testing whether it was writingllms.txtor
llms-full.txtwith its ownfull ? long : short(Clean Code G15, selector arguments). Each
section is now one row (model bucket, formatter, compact heading, full heading),renderpicks the
heading column once and loops, and the method shrank from 228 lines to 14. The rows were generated
from the old calls, so every heading literal is unchanged. Removingllms-full.txt(#1084) is now
deleting one column.LlmsRendererGoldenTest, 548 cases recorded from the old renderer, pins both
files byte for byte for 49 models; swapping two rows failed 4 of them, swapping the heading columns
103, adding one space to one heading 8, and giving one row the wrong formatter 12. -
GuardrailEnforcer.enforceis split into one method per step (internal; no output changes).
The 110-line method collected the guarded elements, read the baseline, recorded it, warned when
nothing was recorded, compared in two directions and reported the result. It is now 23 lines that
read as those steps, callingguardedElements,readBaseline,recordBaseline,
warnNothingRecorded,reportChangedShapes,reportVanishedElementsandreportResult.
GuardrailEnforcerTest, 23 cases written first and green on the old method, pins every branch's
return value, diagnostic text,enforce.*log event and baseline file. Four deliberate breakages
of the new methods failed it: vanished reported before changed (1 failure), the "passed" note
printed despite violations (3), unsigned elements no longer skipped (2), and a constructor sharing
its path with a method (1). -
Path helpers live in two utility classes (internal; no output changes). The forward-slash
conversion that sidecars, the write cache, module ids and diagnostics compare across machines was
written out as.toString().replace('\\', '/')24 times in 10 files; 18 of them, every one in
processor.internal, now callPathStrings.forwardSlashesorPathStrings.relative(base, path).
The bounded upward walk copied intoModuleRootResolverandReactorRootDetector, each with its
ownMAX_WALK_UP = 64, isAncestors.firstMatching.ModuleSidecar'sBACKSLASHconstant, used
only for the conversion, is gone.AIGuardrailProcessor's six copies stay for now (#1101).
PathStringsTestandAncestorsTestwere written first and failed to compile against the
missing classes. MakingforwardSlashesreturn its input failed 34 tests across 14 classes in the
full suite on Windows, and making the walk skip its starting directory failed 11. -
Gradle wrapper 9.8.1 → 9.9.1 (11 wrappers).
gradle.versionin the parent moves to the
current release (services.gradle.org/versions/current), andtools/sync-version-mirrors.py
rewrites everygradle-wrapper.properties. 9.9 also ships a newgradlew.battemplate, whose
error branches now exit throughexitWithErrorLevel, and a newgradle-wrapper.jar(SHA-256
621008af..., the checksum Gradle publishes for 9.9.1); both are what 9.9.1's ownwrapper
task writes, and all 11 copies are byte-identical.gradlewis unchanged.
Deprecated
llms-full.txtis deprecated, and removed in the next major version (#1071, #1084). No tool
documents reading a repository-rootllms-full.txt, and the llms.txt standard (llmstxt.org) never
names the file; PLATFORMS.md attributed it to Windsurf Cascade, but Devin Desktop's docs name
llms.txtonly as their own site index. VibeTags still writes it, and an existing project's
output does not change, but every build that opts in now gets one compiler WARNING naming
llms.txtas the replacement, including a rebuild the early exit skips, andvibetags.log
recordsplatform.deprecated key=llms_full file=llms-full.txt replacement=llms.txt. A build
with-Werrorthat opts intollms-full.txtnow fails; delete the file (keepllms.txt) to
clear it. The "no AI config files found" note no longer offers it, andvibetags init --list
marks it[deprecated, use llms.txt]. This restoresDeprecatedServices, which 1.4.0 removed
with its last row (#720).DeprecatedServicesTest, aSourceDigestEarlyExitEndToEndTestcase
and twoInitCommandTestcases pin it; the early-exit case failed before the change.
Fixed
-
Under
vibetags-ksp, the final round still finds the first round's types after a second round
(#1122). When another KSP processor generates a file, KSP runs a second round, and the adapter
replaced its element model with one built from that round's new files only. javac'sElements
answers for every round's types; under KSP the final round'sgetTypeElementand
getPackageElementreturned null for everything declared in round 1. The models are now layered.
AKspLifecycleTestcase with a generating processor failed before the fix (only the generated
type was found). The issue's other two points did not hold up: check mode fails on drift, never on
a warning, under javac as under KSP, and kotlinc 2.4.21 rejects a VibeTags annotation on a
typealiaswithWRONG_ANNOTATION_TARGET, so such a guardrail fails the build rather than
being dropped. -
Under
vibetags-ksp, a guardrail value from another module's constant no longer lets an unchanged
rebuild be skipped (#1121). Without the Tree API,MethodBodyGuardrailScannercounts the
annotation values the round's sources do not spell out, and the source digest vouches only for a
round with none (#1062). It found the annotations by looking their types up by name, and the KSP
element model holds only the consumer's own types, so it counted nothing: a Kotlin
@AILocked(reason = Shared.REASON)was vouched for, and afterREASONchanged in its module the
next build exited early with the old text in every guardrail file. The KSP elements now hand over
the values each use wrote (UseSiteAnnotationValues), and an element model offering neither
mirrors nor values is never vouched for.KspLifecycleTestfailed before the fix with the
source-digest exit on the second run; aSourceDigestWithoutTreeApiTestcase fails when the
fallback is removed. -
A Gradle
include(...)spread over lines declares its subprojects, and a module round locks
when a declared sibling opted in (#1120).ReactorRootDetector.gradleIncludesread
settings.gradle(.kts)line by line and kept lines starting withinclude, so the multi-line
form Gradle's init template writes yielded no subproject: the root round of such a reactor
generated unlocked on its first build (the #1081 race), and the detached-module and shared-identity
warnings missed it. It now reads the whole file with comments removed;includeBuild, which it
used to count,includeFlatand the wordincludeinside a string literal are not
subprojects. Separately, a module round with no opt-in in
the root or its own directory skippedGenerationLockwhile it still saved its sidecar and
flushed.vibetags-cacheat the root, racing a sibling that had opted in; it now also locks when
the root's build declares an opted-in sibling. New cases inReactorRootDetectorTestand
ParallelReactorGenerationTestfailed before the change. -
Modules sharing one directory no longer read each other's sidecars as their own (#1119). In a
Gradle build configured from one root build file (-Avibetags.module,
examples/gradle-shared-buildfile), every module records the root as its directory, so the
partial-round guard's containment test matched the sibling's sidecar: its elements read as
missing in every round, the missing-element condition always held, and one annotated source the
build excluded refused every later round of that module, leaving its guardrail files frozen. A
sidecar of another module that recorded source roots now describes this round only if one of
them is a root this round compiles. The walk for a module's own deleted elements likewise covers
only its recorded roots when its directory is shared, because walking the root found the
sibling's file declaring a type of the same name and kept a deleted guardrail alive. Two new
PartialRoundGuardrailLossTestcases failed before the fix, and disabling either half fails its
own case. -
@AIArchitecture(cannotReference)is enforced under Gradle (#1118).ArchitectureRulecalled
Trees.instanceon theProcessingEnvironmentit was given, and Gradle's incremental processing
always hands the processor a decorator thatTrees.instancerejects. The rule caught the
IllegalArgumentException, printed a NOTE thatcannotReferencewas not checked, and an illegal
import compiled cleanly on every Gradle build. It now gets the Tree API through
SourcePositionResolver.treesFor, which unwraps the decorator, as every other Tree-API consumer
already did.WrappedProcessingEnvironmentTestcompiles an illegal import behind a wrapper and
failed with the NOTE before the fix. -
central-month-usage.shcounts a version published in several deployments once per
deployment (#1111). It counted one release per group and version, so vibetags 1.4.0, published
as five per-module deployments, counted as one and October 2026 read 7 where Central counted 11.
On repo1 a one-bundle release lands every artifact in the same minute (vibetags 1.4.1 and 1.4.2,
async-test-lib 1.12.4 and 1.14.3), while 1.4.0's modules landed 5 to 15 minutes apart. The
counter now splits a group and version where its artifacts' publish times are more than 2
minutes apart, and October reads 11. A newcentral-month-usage.test.shcase (two artifacts in
one burst across a minute boundary, a third five minutes later) failed first. -
A
.vibetags-mirrorVibeTags cannot use is warned about (#1098). A config that could not be
read, or that held a source line that is not a valid path on this OS (on Windows,../modules/*
written without itsglob =key), was ignored in silence: its module got no mirrored rules and
the build stayed green. Every build now warns once per such config, naming the file and the line,
and a rebuild that changes nothing warns again (#1063).MirrorConfig.unusablereports them;
the warning is hosted with the other warnings about state on disk. Tests inMirrorConfigTest,
MirrorEndToEndTestandShortCircuitStateWarningTestfailed first against a stub that
reported nothing. -
The detached-module warning (#296) reads module declarations the way the rest of the build does
(#1096).ReactorRootDetector.findReactorRootAbovematched a literal<module>path</module>
substring, so a module declared as a Maven 4<subproject>or as a whitespace-padded
<module> core </module>that compiled as its own root got no warning, and its guardrails were
silently missing from the reactor's merged files. The same substring test made a Gradle
include ':payments-core-extra'declarepayments-core, a warning on a project nothing
includes. It now asksdeclaredModules, the parser the root round's lock signal (#1081) already
uses. ThreeReactorRootDetectorTestcases, one per shape, failed before the change. -
A file that appears while the writer is creating it is merged into, not replaced (#1087). The
writer reads a guardrail file, splices its block into what it read and moves the result into
place. When the read found no file, the result was the generated block alone, and the move
replaced whatever was there by then. Onwindows-latestCI, four threads of
GuardrailFileWriterSharedFileAsyncTest(8 writers sharing oneCLAUDE.md, the shape of a
mvn -Tor Gradle--parallelreactor) saw aCLAUDE.mdthat was only the block, the
developer's preamble and appendix gone; a stat that reports the file missing while another
module's rename replaces it is the likely cause, and it did not reproduce locally in 3 runs. A
write merged from no file now moves into place only if no file is there. If one is, the writer
logswrite.retry file= reason=appeared-during-write attempt=and merges again from that file;
after 3 attempts it leaves the file as it is, warns, and logswrite.skip reason=appeared-during-write attempts=3. On POSIX the JDK checks the target before
rename(2), so a file created between the two is still replaced there. The new
GuardrailFileWriterAppearedFileTestcreates the file at the writer'swrite.commitevent, the
last step before the move, forCLAUDE.mdandgreptile.json; all three of its cases failed
before the change. -
One malformed
.vibetags-mirrorno longer hides every mirror target found after it. A source
line that is not a valid path on this OS (a NUL anywhere; on Windows also an ordinary line such as
../modules/*written withoutglob =) madeMirrorConfig.loadthrowInvalidPathException.
Discovery caught it at the parent directory's level, so the targets after the bad one in walk order
were silently dropped and their modules got no mirrored rules. Such a config now counts as absent,
like an unreadable one; the whole file rather than the line, because dropping the only source line
would mean "mirror from every module". It is still ignored without a warning (#1098). A new
MirrorConfigTestcase failed before the change. -
The root round of a reactor locks on its first build too (#1081). The #1074 fix below locked
the root's own round only once.vibetags-generate.lockexisted, so on the first parallel build
of a Gradle root project with sources (or aftergit cleanremoved the gitignored file), the root
round could start before any subproject had locked and generate unlocked beside them. It now also
locks when its build declares subprojects (<module>or<subproject>inpom.xml,includein
settings.gradle(.kts)) and the root or one of those subprojects opted in. A single-module build
and a project with no opt-in still get no lock file. Three newParallelReactorGenerationTest
cases (Gradle root, Maven root, subproject-only opt-in) failed before the change; two more pin
that neither a settings file naming only the root project nor an unopted reactor gets a lock. -
Two more kinds of round generate under the reactor's generation lock (#1074). A module whose
own directory opted in, under a root that did not, still saves its sidecar and flushes
.vibetags-cacheat the root, and took no lock, so a sibling's flush could drop its changes. And
a Gradle root project with sources of its own compiles alongside its subprojects and merges every
sidecar into the root files, but the root's own round never locked. A module round now also locks
when its own directory opted in, and every round, the root's included, locks once
.vibetags-generate.lockexists, which the first sibling to lock leaves behind. A single-module
build still gets no lock file. Tested byParallelReactorGenerationTest, which holds the lock and
asserts both rounds wait for it; both failed before the change. -
Two modules sharing one root no longer silence each other's
vibetags.log(#1079). Under
mvn -Tor Gradle--parallelin one JVM, both modules configured the same Logback logger,
keyed only by the root. The second module's setup replaced the first one's appender, and with it
any per-module-Avibetags.log.path, and the first module to finish stopped the appender the
other was still logging through, so its later events, log-contract events among them, were
dropped. The logger is now keyed by root and compiling thread. Two new
VibeTagsLoggerConcurrencyTestcases (a sibling shutting down mid-compilation; two log paths
under one root) failed before the change. -
A failure in the final round now releases
vibetags.log(#1075).process()downgrades a
RuntimeExceptionto a warning, but every exit that releases the log sits on a path a throw
skips, so a generation that failed left the appender attached and the file open, locked on
Windows, for the rest of a Gradle or Maven daemon. The guard now releases it when the failing
round is the last one.ProcessorFailureGuardTestthrows from inside generation and asserts the
round left no logger configured; it failed before the change. -
Mirrored rule files honour
-Avibetags.module(#1076).MirrorWriterderived the source
module's id from the directory layout, so two modules whose layouts collide (libs/coreand
libs_coreboth lay out aslibs_core) and that were each given an id of their own still wrote
and cleaned up under onemirrored-<id>-prefix, and each compile deleted the other's mirrored
files. It now uses the region id the processor resolved. A module that already sets
-Avibetags.moduleand mirrors into a target mirrors under the new name from the next build;
the files under the old layout-derived name are no longer anyone's to clean up, so delete them by
hand.MirrorEndToEndTestcompiles the colliding pair and failed before the change. -
Check mode no longer writes
.vibetags-baseline(#1077). Check mode promises to write none
of the files VibeTags manages, but enforcement runs before the check-mode branch, so
-Avibetags.check=truewith-Avibetags.baseline.update=truerecorded a fresh baseline, and a
changed@AIContractsignature was approved by the very run meant to catch it. The update is now
ignored with a warning in check mode, and the families-Avibetags.enforcenames are still
checked against the baseline on disk. Two newEnforcingModeEndToEndTestcases failed before the
change. -
An unchanged module build no longer rewrites
.vibetags-cache(#1080). The processor binds
its run context ininit(), before the module is known. In a cache with one section per module
that compared the context with no section at all, marked the cache dirty on every build, and the
next flush rewrote the file with the bytes it already held. The comparison now waits for the
module, whichbindModule()already made.WriteCacheFileFormatTestpins both halves: no rewrite
when the module's context matches (failed before the change), a rewrite when it changed.