Skip to content

VibeTags v1.3.8

Choose a tag to compare

@PIsberg PIsberg released this 28 Sep 03:49
39f438e

[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 calls tools/self-check.sh, and a
    vibetags-self-check pre-commit hook runs the same script on any commit touching
    vibetags/src/, vibetags-annotations/src/, vibetags/pom.xml or README.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 runs ProjectFactsConsistencyTest after
    regenerating. It deletes the gitignored .vibetags-mod-* sidecars and .vibetags-cache first,
    as a clean clone has none (#794). 30–45 s here. SelfCheckGateWiringTest pins 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 ...)", and vibetags.log records
    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 -Werror fails 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 withdrawn TESTING.md fallback, 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> in CLAUDE.md and
    - `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.md went from 13,444 to 12,873 bytes and GEMINI.md from 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
    use ProcessorTestHarness.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 for CLAUDE.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 of AGENTS.md, 562 of
    GEMINI.md and 426 of llms.txt, all loaded on every session by the tools that read them.
    MarkdownSectionMerge joins the bodies section by section and declines, keeping the old
    concatenation, on any shape it does not know. Fourteen renderers declare it, and
    MarkdownSourceSetMergeEndToEndTest fails for one that does not.
  • .vibetags-locks writes 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. LocksReportMerge joins the source sets as a union of lines, and no lock can be
    lost to it: two locked elements always differ in element.

Deprecated

  • .zencoder/rules/ (#845). Zencoder's changelog says custom rules were phased out from March
    2026 and removed in May 2026, naming AGENTS.md as 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 naming AGENTS.md and .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.
    MarkerInProseTest pins 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.
    PartialRoundGuardrailLossTest pins 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.
    GuardrailFileRecoveryEndToEndTest and GuardrailFileWriterEdgeCaseTest pin 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.
    GuardrailLifecycleEndToEndTest and GuardrailFileWriterEdgeCaseTest pin it.
  • A nested module's sidecar written on Windows is no longer pruned by a Linux build of the same
    tree (#868).
    modulePath was Path.toString(), so Windows wrote services\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. MultiModuleAggregationTest pins both sides.
  • Two modules that resolve to the same module id are reported (#869). Ids are sanitised paths,
    so a/b and a_b (or a module named core__test beside core'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.module override that separates them. Ids are unchanged: renaming them would move
    every committed region marker. MultiModuleAggregationTest pins 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 |, so forbidden = {"a,b"} hashed the same as forbidden = {"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-cache miss (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, and Files.createTempFile creates it rw-------, so a rw-r--r-- file (an
    llms.txt a web server reads) became readable by its owner only on its first update, with
    nothing in a diff; files VibeTags created were rw------- 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.
    GuardrailFileWriterCoverageTest pins 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.project and module override) next to the fingerprint recorded under the old one. If
    generation then failed, the next build found both matching and skipped, and llms.txt kept the
    old title. A fingerprint recorded under another context is now dropped as soon as the new one is
    bound. WriteCacheTest pins it.
  • A stale file under Maven's target/generated-sources no longer blocks an annotation removal
    (#866).
    The partial-round guard leaves generated-source trees out of its walk, but matched only
    Gradle's generated segment. 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-sources and generated-test-sources are
    now left out too. PartialRoundGuardrailLossTest pins 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 --- then Owner: 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 live core module read as stale on every build (the short-circuit never fired) and
    its rule-file stems were reported as departed. MultiModuleAggregationTest pins it on Linux.
  • A hand-written AGENTS.md that 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 to CLAUDE.md got a whole generated block appended and a
    .codex/config.toml created; 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.
    AgentsMdSoleFallbackTest pins both pointers.
  • Pasting a marker pair into AGENTS.md beside CLAUDE.md is 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 whether AGENTS.md carries a marker pair.
    SourceDigestEarlyExitEndToEndTest pins 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. A CLAUDE.md saved 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.
    SourceDigestEarlyExitEndToEndTest pins it.
  • The partial-round guard (invariant 17) no longer switches off for a checkout under a directory
    named generated.
    Generated-source trees are left out of the guard by their generated path
    segment, which was looked for in the whole absolute path. A project at /ci/generated/proj had
    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. PartialRoundGuardrailLossTest pins 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 # end trailer. 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, so readAll deleted it and the module dropped out
    of every sibling's output until it recompiled. The trailer is now judged first.
    ModuleSidecarUnreadableScanAgreementTest and ModuleSidecarOnRecordAgreementTest pin 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 @AILocked stayed there while the root
    dropped it, and check mode agreed with the stale file. The same #781 verdict now reaches the
    module-scoped writer. PerModuleOutputEndToEndTest pins 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. PartialRoundGuardrailLossTest pins 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.
    FresherAncestorRegionDuplicateTest pins it, and its @AIContract fixture, which named an
    attribute the annotation does not have and so never compiled, now uses reason.
  • 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. GuardrailFileRecoveryEndToEndTest pins it.
  • A .vibetags-mirror target 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. MirrorEndToEndTest pins it.
  • A rebuild stopped by the fingerprint logs its orphan warning to vibetags.log again. Since
    #860 the orphan check runs after generateFiles() 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.
    SourceDigestEarlyExitEndToEndTest pins 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 skipped generateFiles() whole. A -Werror build
    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, .qwenignore and .aiexclude variants for
    @AIIgnore were 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 -Werror build
    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 init marks deprecated outputs (#854). init --list showed the 22 deprecated
    outputs exactly like current ones, and --platforms gemini created gemini_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 --platforms still 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/ keep chars= limit=12000, re-checked at the vendor the same day.
  • tools/release-notes.sh pins every relative link to the tag, not just changelog-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 than docs/. Every
    relative target is now resolved against docs/: images become raw/<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
    whose git worktree add failed was reported as ERROR and then counted in Built 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 still 1. git worktree add also runs with core.longpaths=true, so a deep TMPDIR on
    Windows no longer fails the checkout with Filename too long.
  • vibetags doctor no 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.