Repository navigation
VibeTags v1.3.8
[1.3.8] - 2026-09-28
Upgrading: what moves in your committed files. A project whose test sources carry guardrails
gets one generated block per Markdown aggregate instead of two stacked copies (#841): AGENTS.md,
GEMINI.md, llms.txt, .cursorrules, .github/copilot-instructions.md and the other prose
files lose their second header and repeated section headings, and the test round's entries move
into the matching section. No guardrail line is dropped: across this repository and its examples,
44 files had 441 lines deleted and 50 re-inserted into merged sections, and no distinct line
disappeared from any of them. A project without annotated test sources sees no change.
A project that opts into a granular directory beside its aggregate (.claude/rules/ with
CLAUDE.md, and the four other pairs) sees every scoped-rules index line rewritten once (#839):
elements are grouped one line per package instead of one line each. The same elements are named,
and no rule file moves.
Added
- The self-check runs before the commit, not one CI round-trip after the push.
build.yml's
"Verify VibeTags' Own Guardrails Are Current" step now callstools/self-check.sh, and a
vibetags-self-checkpre-commit hook runs the same script on any commit touching
vibetags/src/,vibetags-annotations/src/,vibetags/pom.xmlorREADME.md. The drift it
catches had reached CI five times: a line added above a locked method moves its range in
.vibetags-locks(#687, #793, #797, #862), and a regeneration moved the.claude/rules/line
count README.md quotes (#861), so the script also runsProjectFactsConsistencyTestafter
regenerating. It deletes the gitignored.vibetags-mod-*sidecars and.vibetags-cachefirst,
as a clean clone has none (#794). 30–45 s here.SelfCheckGateWiringTestpins both callers to the
script.
Changed
- A rebuild of unchanged sources decides before the collection walk (#834). The fingerprint
short-circuit needed the walk's result, and the walk was most of what a no-op rebuild allocated.
The first round now hashes every source file it was given, with the version, options, module,
opt-ins and.vibetags-*configuration, and skips the walk when that matches the module's last
clean run and every output is still byte-stable. At 1000 annotated classes on files on disk, a
no-op rebuild allocates 18.4 MB of VibeTags' own against 64.2 MB before, and a cold build 55.0 MB
against 51.5 MB for the hashing. It stays off wherever something after the walk needs its
result (check mode, enforcement, inherited or published manifests).init()also reads the root's
sidecars once instead of twice, which is why a rebuild had cost more than a cold build. The note
says "(source digest ...)" where it said "(fingerprint ...)", andvibetags.logrecords
round.skip reason=sources-unchanged. - A build that warns can take the early exit too, and repeats its warnings (#856). Validation
warnings come from the walk, so #834 never skipped a build that raised one, and a project keeping
one warning around walked every element on every rebuild. The warnings and notes validation prints
are now recorded with the source digest (# source-diagnostic:lines in.vibetags-cache) and
printed again by a skipped build, in its first round, anchored to the same element: same text,
same file, line and column, and the same count, so-Werrorfails the rebuild as it failed the cold
build. On the load tests' own fixture, where every 14th class warns, a no-op rebuild at 1000 classes
allocates 18.8 MB of VibeTags' own against 56.9 MB. A build that printed more than 1000 diagnostics,
or whose method-body scanner warned, still walks next time. - Each source file is resolved once per round, and
init()no longer parses sidecar bodies
(#857, #858). Module identity, the early exit's digest and the partial-round ledger each mapped
every root element to its source file themselves; they now share one mapping.init()asked
whether any sidecar records elements, or holds a withdrawnTESTING.mdfallback, by parsing every
sidecar in full; it now streams each past and keeps no rendered body. At 1000 annotated classes on
files on disk, a cold build allocates 49.7 MB of VibeTags' own against 54.6 MB, and a no-op rebuild
17.3 MB against 18.5 MB (the two changes measured together). - The scoped-rules index names each package once (#839). A collapsed aggregate's index wrote one
line per element and repeated the element's whole package on every one. It now writes one line
per package,<elements in="com.example.a">Alpha, Beta</elements>inCLAUDE.mdand
- `com.example.a`: `Alpha`, `Beta`in the Markdown aggregates; the prefix, a dot and a name
are the element again, so nothing is lost and every name stays greppable. On this repository
CLAUDE.mdwent from 13,444 to 12,873 bytes andGEMINI.mdfrom 6,988 to 6,575. Hoisting one base
over the whole index, the alternative #847 named, would have saved about as much but differs per
source set, and the main and test rounds' index lines are merged into one section; a per-line
group merges as it stands. Tests that asserted an element was absent from an indexed file now
useProcessorTestHarness.mentions, because a literal FQN no longer occurs in a grouped line and
those assertions could no longer fail. - Markdown aggregates render one document per module, not one per source set (#841). #839 did
this forCLAUDE.md; every other prose aggregate still stacked the test round's body, header and
all, under the main round's. On this repository that was 289 bytes ofAGENTS.md, 562 of
GEMINI.mdand 426 ofllms.txt, all loaded on every session by the tools that read them.
MarkdownSectionMergejoins the bodies section by section and declines, keeping the old
concatenation, on any shape it does not know. Fourteen renderers declare it, and
MarkdownSourceSetMergeEndToEndTestfails for one that does not. .vibetags-lockswrites its header once per module, not once per source set (#851). A module
with annotated test sources repeated the two header comments and the{"type":"format"}record;
readers skip both, so nothing was misread, but the CI Locked Files Guard parses this file on every
pull request.LocksReportMergejoins the source sets as a union of lines, and no lock can be
lost to it: two locked elements always differ inelement.
Deprecated
.zencoder/rules/(#845). Zencoder's changelog says custom rules were phased out from March
2026 and removed in May 2026, namingAGENTS.mdas the replacement, and its old rules page now
redirects to Skills. The inference the 1.3.7 re-check could not close, whether "custom rules"
meant this directory, is closed by the July 2025 entry that calls the glob-scoped project
instructions "now evolved into Skills" and by a Context Management page that lists no rule files;
both were read in a browser, since the docs refuse other clients. An opted-in build now prints
the deprecation warning namingAGENTS.mdand.agents/skills/, and the directory is still
written until the next major version (#720).
Fixed
- A marker pair shown as an example in a fenced code block is left alone. Each marker owns its
line inside the fence, so the writer took the example for the managed block: its contents were
replaced by the generated rules on every build, rendered as code no agent reads as guardrails,
and a real block below it was never refreshed. The block is now looked for outside fences.
MarkerInProseTestpins it. - A reactor root that compiles sources of its own no longer blocks its modules' writes. The
partial-round guard consulted every sidecar whose directory contains the round's sources, and the
root's contains every module's. Its elements are never produced by a module round, so while that
sidecar existed, a module that keeps one annotated source out of its build was refused as partial
on every compile, its first included. A parent module's sidecar is no longer consulted.
PartialRoundGuardrailLossTestpins it. - A stray START marker no longer costs the text after it (#865). A marker file with a START
line and no END was repaired by deleting everything after START, on the assumption that it was a
generated block that lost its END. When the START line was an example the developer pasted, their
text after it went with it. The repair now runs only when the generated header follows START;
otherwise the file is left untouched with a WARNING saying how to fix it. The repair also no
longer runs for a round with no annotations, the one case every other path refuses.
GuardrailFileRecoveryEndToEndTestandGuardrailFileWriterEdgeCaseTestpin both. - A rule file that could not be deleted is retried by the next build (#867). An orphaned rule
file the sweep failed to remove (held open by an editor or indexer on Windows, a read-only
directory) kept its write-cache entry, so every later unchanged build short-circuited and the
stale guardrail stayed until a source changed; the failure was only a DEBUG line. It is now a
WARNING, and the failure is recorded as a cache row that matches no file, as a failed write is.
GuardrailLifecycleEndToEndTestandGuardrailFileWriterEdgeCaseTestpin it. - A nested module's sidecar written on Windows is no longer pruned by a Linux build of the same
tree (#868).modulePathwasPath.toString(), so Windows wroteservices\api, which Linux
resolves as one filename, reads as a departed module, and prunes with its rule-file stems. It is
now written with forward slashes and read that way whatever wrote it. Sidecars are gitignored:
a Windows build rewrites each nested module's sidecar once, which costs one full reactor round
and changes no committed file.MultiModuleAggregationTestpins both sides. - Two modules that resolve to the same module id are reported (#869). Ids are sanitised paths,
soa/banda_b(or a module namedcore__testbesidecore's test source set) shared one
sidecar and one region, and each one's build silently replaced the other's guardrails; the only
warning blamed the compilation's sources. A WARNING now names both modules and the
-Avibetags.moduleoverride that separates them. Ids are unchanged: renaming them would move
every committed region marker.MultiModuleAggregationTestpins it. - Editing an annotation's array or moving text between two of its members is no longer skipped
as unchanged (#870). The fingerprint extractors joined array members with a bare,and fields
with|, soforbidden = {"a,b"}hashed the same asforbidden = {"a", "b"}, and
@AITemporary(expiresOn = "x|y", reason = "z")the same as("x", "y|z"), while each pair
renders differently. Every member is now length-prefixed. Upgrading costs every consumer one
.vibetags-cachemiss (one full generation, no committed file changes);
BuildFingerprintPinnedValueTest's literals moved for this reason.BuildFingerprintUnitTest
pins both cases. - An updated file keeps its POSIX permissions (#871). Every write goes through a temp file moved
over the target, andFiles.createTempFilecreates itrw-------, so arw-r--r--file (an
llms.txta web server reads) became readable by its owner only on its first update, with
nothing in a diff; files VibeTags created wererw-------too. A rewrite now keeps the file's
own mode, and a new file gets what a default umask gives: owner read/write, read for group and
others where the directory grants it, never write for them. No change on Windows.
GuardrailFileWriterCoverageTestpins both on POSIX. - A changed project name is not lost to a generation that fails (#872). The processor flushes
the write cache before it generates, and that flush wrote the new run context (the
-Avibetags.projectand module override) next to the fingerprint recorded under the old one. If
generation then failed, the next build found both matching and skipped, andllms.txtkept the
old title. A fingerprint recorded under another context is now dropped as soon as the new one is
bound.WriteCacheTestpins it. - A stale file under Maven's
target/generated-sourcesno longer blocks an annotation removal
(#866). The partial-round guard leaves generated-source trees out of its walk, but matched only
Gradle'sgeneratedsegment. Under Maven, a generated file an earlier run left on disk that names
the annotations made every round look partial once an annotation was genuinely removed, so the
removal was refused until a clean build.generated-sourcesandgenerated-test-sourcesare
now left out too.PartialRoundGuardrailLossTestpins both layouts. - Stripping an orphaned rule file no longer deletes a hand note that contains
---(#875). The
sweep decided "only front matter is left" by searching for the next---anywhere, so a file
whose remaining hand-written text was---thenOwner: payments team ---read as an empty
header and was deleted. It now uses the writer's front-matter parser, whose fences own their
lines, and rewrites a kept file atomically like every other write.CleanupGranularDirectoryTest
pins it. - A module directory whose name ends in a space is no longer read as departed (#874). The
staleness checks read a sidecar's module path trimmed, while the full read keeps it as written, so
on Linux a livecoremodule read as stale on every build (the short-circuit never fired) and
its rule-file stems were reported as departed.MultiModuleAggregationTestpins it on Linux. - A hand-written
AGENTS.mdthat only mentions the marker is no longer opted in beside another
AI file. The escape hatch from the sole-file rule (invariant 4) is a marker pair, but the check
looked for the START text anywhere in the file. A pointer saying "VibeTags edits the region
after<!-- VIBETAGS-START -->" next toCLAUDE.mdgot a whole generated block appended and a
.codex/config.tomlcreated; a pointer with a START line and no END had its text after START
replaced. The check now requires the line-owned START/END pair the writer refreshes.
AgentsMdSoleFallbackTestpins both pointers. - Pasting a marker pair into
AGENTS.mdbesideCLAUDE.mdis picked up by the next build. The
build that skips such a file prints a NOTE telling the user to paste a VIBETAGS-START/END pair,
but the early exit (#834) hashed only which opt-in files exist, not that content, so the next
build with unchanged sources took the exit and left the pasted pair empty until a source
changed. The source digest now includes whetherAGENTS.mdcarries a marker pair.
SourceDigestEarlyExitEndToEndTestpins it. - A file that failed to write is retried by the next build. The write warned once and the
build was still recorded as clean; a file the writer never managed to write had no write-cache
entry, and an absent entry counts as stable, so every later build with unchanged sources took the
early exit or the fingerprint short-circuit. ACLAUDE.mdsaved in Latin-1 and re-saved as
UTF-8, or one locked by an editor on Windows, never received its guardrails until a source
changed. The failure is now recorded as a cache row that matches no file.
SourceDigestEarlyExitEndToEndTestpins it. - The partial-round guard (invariant 17) no longer switches off for a checkout under a directory
namedgenerated. Generated-source trees are left out of the guard by theirgeneratedpath
segment, which was looked for in the whole absolute path. A project at/ci/generated/projhad
no source root left, every round counted as complete, and an incremental round of one source
deleted the rule files of the two it was never shown. Only the part below the VibeTags root is
judged now.PartialRoundGuardrailLossTestpins it. - A sidecar cut off inside a value is kept, not deleted. A torn write is skipped and never
deleted (#553), judged by the missing# endtrailer. But both sidecar loaders decoded each value
before they looked for the trailer, and a cut that leaves a dangling Base64 character (one cut
point in four) made the file read as corrupt, soreadAlldeleted it and the module dropped out
of every sibling's output until it recompiled. The trailer is now judged first.
ModuleSidecarUnreadableScanAgreementTestandModuleSidecarOnRecordAgreementTestpin it. - A module whose last annotation is removed drops it from its own module-scoped file too. Since
#781 an emptied source set rewrites the shared root files it withdrew from, but a module that opts
into its own file (module-core/CLAUDE.md) decided whether an empty round may rewrite it by
whether the round found annotations, so the removed@AILockedstayed there while the root
dropped it, and check mode agreed with the stale file. The same #781 verdict now reaches the
module-scoped writer.PerModuleOutputEndToEndTestpins it. - A module with annotated tests and one annotated main source excluded from the build writes
again. The partial-round guard (invariant 17) asks whether a sidecar describing the round's
source tree names an element the round did not produce, and the module's test sidecar describes
the same directory. A main round never produces test elements, so once the tests had compiled the
question was always yes, and the excluded source (a<excludes>entry) answered the other half:
every main round was refused as partial and an edited annotation was never generated. A sidecar
of another source set is no longer consulted.PartialRoundGuardrailLossTestpins it. - Check mode no longer reports drift on the compile that retires its own ancestor region. A
build that files itself under the root identity (#621's fallback) saves a sidecar that the prune
retires at once, so generation changes nothing. Check mode simulated that save by adding the
in-memory sidecar after the on-disk ones had been pruned, merged every shared element twice, and
failed with "2 guardrail file(s) are out of date". It now prunes the same list generation does.
FresherAncestorRegionDuplicateTestpins it, and its@AIContractfixture, which named an
attribute the annotation does not have and so never compiled, now usesreason. - A generated file saved with a UTF-8 byte order mark keeps one block. A block that opens the
file (the usual shape of a file opted in empty) was no longer found once an editor added a BOM:
U+FEFF is not whitespace, so the START marker did not own its line, the file was treated as a
pre-marker legacy file, and the old block's markers stayed as text above a second, new block.
The BOM is now looked past and written back.GuardrailFileRecoveryEndToEndTestpins it. - A
.vibetags-mirrortarget created after a module's last build is mirrored into on the next
one. The config lives in a sibling module, outside what the fingerprint and the source digest
hash, and only a config that already existed was watched. Creating one, or a granular directory
in an existing target, left the next unchanged build of every source module on a short-circuit,
and nothing was mirrored until a source changed. The mirror targets' state now reaches both keys
(invariant 12), only when a target exists.MirrorEndToEndTestpins it. - A rebuild stopped by the fingerprint logs its orphan warning to
vibetags.logagain. Since
#860 the orphan check runs aftergenerateFiles()returns from its fingerprint short-circuit, but
that return releases the log, so the warning reached the console and never the log (invariant
15). The check now reopens the log with the same options, as the rule-file length check does.
SourceDigestEarlyExitEndToEndTestpins it. - A rebuild that takes the early exit repeats the deprecated-output and module-identity warnings
(#859).generateFiles()raises them before its fingerprint short-circuit, so every no-op
rebuild printed them until #834's early exit skippedgenerateFiles()whole. A-Werrorbuild
with a deprecated opt-in failed cold and passed every rebuild after it. The orphan warnings
are raised after that short-circuit; see #860 below. - Every rebuild repeats the orphan warnings (#860). "@AILocked used but .aiexclude (hard
guardrail) is missing" and the.cursorignore,.qwenignoreand.aiexcludevariants for
@AIIgnorewere printed by a cold build and by no rebuild:generateFiles()raises them after
its fingerprint short-circuit, and the early exit (#834) never reaches it. A-Werrorbuild
failed cold and passed after. A build stopped by the fingerprint now runs the check once
generation returns, and the warnings are recorded with validation's, so an early-exited build
replays them (#856). The locked method is unchanged. The replay prints them in the first round,
ahead of the deprecated-output warning a cold build prints first; the count and text match. vibetags initmarks deprecated outputs (#854).init --listshowed the 22 deprecated
outputs exactly like current ones, and--platforms geminicreatedgemini_instructions.md
without a word, while the processor already leaves them out of its own suggestions. Each is now
listed with[deprecated, use ...], naming the same replacement as the compiler warning, and
naming one in--platformsstill creates it but prints a warning.- Antigravity rule files are measured against its 24,000-byte cap, not 12,000 characters (#850).
Antigravity's rules page now says it "truncates any single rule file that exceeds 24,000 bytes";
the 12,000-character figure #701 used is gone from it. An.agents/rules/file of 12,001 ASCII
characters no longer warns, and one of 9,000 CJK characters (27,000 bytes), which no character
count flags, now does. The WARN event for that directory is
validation.rule-file-over-limit file= bytes= limit=24000; Devin Desktop's.devin/rules/and
.windsurf/rules/keepchars= limit=12000, re-checked at the vendor the same day. tools/release-notes.shpins every relative link to the tag, not justchangelog-assets/(#849).
A section that embedded plots as../load-tests/...produced notes whose images 404 on the
release page, because GitHub resolves them from the repository root rather thandocs/. Every
relative target is now resolved againstdocs/: images becomeraw/<tag>/URLs and other files
blob/<tag>/URLs. A link that climbs out of the repository makes the script refuse and emit
nothing.- The consumer sweep no longer counts an error before the build as a build (#848). A consumer
whosegit worktree addfailed was reported asERRORand then counted inBuilt N of M, so
one sweep's footer read "Built 5 of 5" with a consumer never compiled. The footer now reads
Built 4 of 5 consumer(s): 1 failed, 1 errored before building, 0 skipped., and the exit status
is still1.git worktree addalso runs withcore.longpaths=true, so a deepTMPDIRon
Windows no longer fails the checkout withFilename too long. vibetags doctorno longer scans other checkouts below--dir(#842). Its Groovy and Kotlin
source scans walked into.claude/worktrees/, where Claude Code keeps full checkouts of the
repository, and reported each copy of a source as a finding. On this repository that was 25
Groovy files where 1 is real. Any directory holding.git, as a file (a worktree) or a
directory (a nested clone), is now skipped.