baldart 4.52.2 → 4.52.4

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.52.4] - 2026-06-18
+
+**SSOT hygiene: `/cont` (context-primer) no longer restates the code-search tier hierarchy inline.** Follow-up to v4.52.3. The prompt template `context-primer` hands to `codebase-architect` re-stated the "prefer LSP/graph over grep for symbols" guidance inline (step 3a) instead of citing the protocol modules — so after v4.52.3 added the anti-flail rule to `code-search-protocol.md` / `code-graph-protocol.md` / the `codebase-architect` system prompt, that inline copy was the one spot that didn't carry it. Functionally harmless (the spawned `codebase-architect` already governs via its own system prompt + the protocols), but a latent drift surface. Trimmed step 3a to a citation of both protocol modules ("follow their tier order, budgets, and anti-flail rule — don't restate them here"), keeping context-primer's own task shaping (canonical-router-first, agent memory, backlog, git, verification) intact. Verified no other skill restates the hierarchy (`lsp-bootstrap`'s line is a user-facing confirmation, not a protocol copy). **PATCH** (doc/guidance hygiene; no behaviour change — the search behaviour was already governed by the agent + protocols; no `baldart.config.yml` key).
+
+### Changed
+
+- **`framework/.claude/skills/context-primer/SKILL.md`** — step 3a of the SEARCH STRATEGY block now cites `code-search-protocol.md` + `code-graph-protocol.md` for tier order / budgets / anti-flail instead of restating the LSP/graph-over-grep hierarchy inline.
+
+## [4.52.3] - 2026-06-18
+
+**`codebase-architect`: structural tier (graph/LSP) is the PRIMARY source for symbol queries, with a hard anti-flail grep cap.** Diagnosed from a real `/prd` discovery run: a foreground `codebase-architect` verification burned its whole turn budget (56 tool uses, 88.1k tokens) grepping ~10× for one function (`createDraft`) inside an 8000-line re-export barrel, **terminated mid-investigation before producing its `totals:` report** (the truncation `/prd` then mis-recovered by resuming the completed agent in the background, breaking the foreground/blocking discovery contract). Root cause: the agent reached for the graph (`graphify explain`, which located the symbol instantly) only *after* the grep flail — because the protocols framed graph/LSP as "escalation" (i.e. *after* grep) and excluded the graph from single-symbol queries entirely, and nothing capped per-symbol grep. Fixed by three surgical guidance edits: (1) `codebase-architect` step 3 now routes symbol location/relation queries to the structural tier **first** when its flag is on (grep is the fallback), with an **anti-flail heuristic** — don't grind grep to locate one symbol; after ~2 misses (or on a barrel / very large file) switch tools: to `graphify explain`/`query` or LSP `go-to-definition` when a flag is on, or — **when neither flag is on (the default config)** — read the file's exports/headings directly instead of full-text-grepping it again; (2) `code-search-protocol.md` adds the same flag-aware per-symbol anti-flail rule to **Budget** + a fallback rule (LSP off & grep can't find a definition → graph is a valid locator); (3) `code-graph-protocol.md` narrows the "graph adds nothing for single-symbol" exclusion — the graph IS a valid fallback for *locating* a definition when grep/LSP miss on a barrel. The downstream `/prd` post-condition gap (how to react to an incomplete foreground grounding return) is intentionally **not** fixed here — this release attacks the root cause (budget burn), not the symptom. The "prefer LSP/graph over grep" guidance already existed and was ignored on the incident run; the reframe + graph-as-locator fix are net-positive regardless, but the behavioural claim is unverified — the real test is the next run. **PATCH** (behaviour-correcting guidance to existing agent + protocol modules; no new agent/skill/capability, no `baldart.config.yml` key).
+
+### Fixed
+
+- **`framework/.claude/agents/codebase-architect.md`** — step 3 reframed: structural tier first for symbol location/relation queries when `has_lsp_layer` / `has_code_graph` is on; grep is the fallback; new flag-aware anti-flail heuristic (after ~2 grep misses, escalate to `graphify explain`/`query` or LSP if a flag is on, else read exports/headings directly — never grind grep on a barrel).
+- **`framework/agents/code-search-protocol.md`** — **Budget** gains a flag-aware per-symbol anti-flail rule (with a no-flag fallback to reading exports/headings); **Fallback rules** gain "LSP off & grep can't locate a definition → code graph is a valid locator".
+- **`framework/agents/code-graph-protocol.md`** — the single-symbol exclusion is narrowed to *reference enumeration*; `graphify explain`/`query` is now documented as a valid fallback for *locating* a symbol's definition on barrel/large files, with a matching query-type table row.
+
 ## [4.52.2] - 2026-06-18
 
 **Anti-hardcoded gate: kill the false positives — the generated ESLint config now allowlists only user-facing JSX attributes.** v4.52.0's `mode: 'jsx-only'` flagged *every* JSX attribute string, so on a real component-heavy codebase it drowned the signal in technical props — `variant="inset"`, `size="lg"`, `href="/login"`, `padding="md"` were all reported as "hardcoded user-facing strings". Measured on a production app: **3260 raw findings, mostly false positives.** Fixed by adding `'jsx-attributes': { include: ['placeholder','title','alt','label','aria-label'] }` to the generated `eslint.i18n.config.mjs` / `.eslintrc.i18n.json`, so attribute checks are restricted to the genuinely user-facing ones while JSX text nodes are still fully checked. Same codebase after the fix: **~1500 findings, 0 technical-attribute false positives** — every remaining finding is a real hardcoded label. Verified against `eslint-plugin-i18next`'s `shouldSkip` include-allowlist semantics. **PATCH** (tightens the generated gate config to be usable on real codebases; no new key, no behaviour change beyond fewer false positives).

package/VERSION

@@ -1 +1 @@
-4.52.2
+4.52.4

package/framework/.claude/agents/codebase-architect.md

@@ -144,8 +144,26 @@ Before providing any architectural guidance or implementation advice, follow thi
 2. **Git log** (when the router is thin): `git log --oneline -20 --grep="<feature>"`
    Limit to 20 results. Don't search `--all` unless the feature branch is unknown.
 
-3. **Targeted grep**: grep for 2-3 specific identifiers
-   (function names, file patterns), NOT broad keyword sweeps across the entire codebase.
+3. **Code search — structural tier first, grep capped.** Route by query shape
+   BEFORE reaching for grep:
+   - **Locating / relating a symbol** (where a function/type/class is defined, who
+     calls it, what connects to it): the structural tier is the **PRIMARY source**
+     when its flag is on — LSP `go-to-definition` / `find-references`
+     (`features.has_lsp_layer`) and the Graphify graph (`features.has_code_graph`,
+     see the escalations below). Grep is the **fallback** here, not the first move:
+     it conflates textual collisions and is worst on large / barrel files.
+   - **Anti-flail gate:** don't grind grep to locate one symbol. After ~2 misses —
+     or when the target is a barrel / re-export / very large file — switch tools
+     instead of grepping again:
+     - structural tier **on** → `graphify explain "<symbol>"` / `graphify query`,
+       or LSP `go-to-definition`;
+     - **neither flag on (the default)** → don't keep full-text-grepping the barrel
+       either; read its exports/headings directly (step 4 below:
+       `grep "^export\|^function\|^class"`) to find the definition.
+     Repeated grep on a barrel burns the turn budget and can make you return
+     *before* you synthesize the report.
+   - **Textual patterns** (a comment, magic string, config key, regex): grep for
+     2-3 specific identifiers, NOT broad keyword sweeps across the entire codebase.
 
    **Code graph escalation (since v4.21.0):** when `features.has_code_graph: true`
    AND the question is **structural/relational** (what connects X to Y,

package/framework/.claude/skills/context-primer/SKILL.md

@@ -83,14 +83,12 @@ SEARCH STRATEGY — canonical-router-first, verify-only-if-needed:
    c. Git: `git log --oneline -10 --grep="{keywords}"` (10 results max).
 
 3. Broader search (when steps 1-2 are thin):
-   a. Grep the project's source root for 2-3 specific identifiers from steps 1-2.
-      When `features.has_lsp_layer: true` AND the identifier is a symbol (function /
-      type / class name, not a free-text phrase), prefer LSP `find-references` /
-      `go-to-definition` over Grep — it filters textual collisions before any file
-      read. Cap at 3 LSP calls, then fall back. See `framework/agents/code-search-protocol.md`.
-      When `features.has_code_graph: true` AND the question is structural/relational
-      (how X connects to Y, impact, clusters), prefer the Graphify code graph
-      (`graphify query`/`path`/`affected`) — see `framework/agents/code-graph-protocol.md`.
+   a. Search for 2-3 specific identifiers from steps 1-2, routing by query shape
+      per `framework/agents/code-search-protocol.md` (symbols → LSP when
+      `has_lsp_layer`) and `framework/agents/code-graph-protocol.md` (structural /
+      relational → Graphify when `has_code_graph`); grep is the fallback for textual
+      patterns. Follow those modules' tier order, budgets, and anti-flail rule —
+      don't restate them here.
    b. Read key file headers (first 50 lines) to identify structure.
    DO NOT read `${paths.prd_dir}/` or `${paths.references_dir}/` files in full —
    route via the registry and read only the specific section you need.

package/framework/agents/code-graph-protocol.md

@@ -52,8 +52,13 @@ For a **structural / relational** query, the order is:
 3. **Grep** — textual patterns (comments, magic strings, config keys).
 4. **Git log** — when/why something changed.
 
-For a **symbol or textual** query, skip the graph and start at LSP/Grep per the
-code-search-protocol — the graph adds nothing there.
+For a **symbol or textual** query, start at LSP/Grep per the code-search-protocol
+— the graph adds nothing to *enumerating* a known symbol's references. **Exception
+— symbol location:** when you cannot find where a symbol is *defined* (Grep misses
+on a barrel / re-export file and LSP is off or also misses), `graphify explain
+"<symbol>"` / `graphify query` IS a valid fallback for locating it. Do not keep
+grepping a large barrel file — see the per-symbol grep cap in
+`code-search-protocol.md` → Budget.
 
 ## Native commands (all offline, 0 API cost)
 
@@ -79,6 +84,7 @@ Run via Bash (the CLI is on `$PATH` once installed); `--graph` defaults to
 | "what breaks if I change X" / impact | code graph (`affected`) |
 | "which parts form a cluster / the core abstractions" | code graph (`GRAPH_REPORT.md`) |
 | `handleSubmit`, `UserSchema` (single symbol refs/def) | LSP |
+| can't locate where a symbol is defined (Grep/LSP missed, barrel file) | code graph (`explain`/`query`) as fallback |
 | `"TODO: …"`, a config key, a regex | Grep |
 | "when did X change" | Git log |
 

package/framework/agents/code-search-protocol.md

@@ -70,6 +70,15 @@ Before picking a tier, classify the query:
   the picture is still unclear, escalate to a direct file read —
   don't keep ping-ponging through references.
 - **Grep**: existing project budget (typically 15–25 calls per agent).
+- **Grep per symbol (anti-flail)**: don't grind grep to locate one symbol's
+  definition. After ~2 misses — or when the target is a barrel / re-export / very
+  large file — switch tools instead of grepping again: the structural tier when its
+  flag is on (LSP `go-to-definition`, or the code graph `graphify explain
+  "<symbol>"` / `graphify query` per `code-graph-protocol.md`); when **neither is
+  on (the default)**, read the file's exports/headings directly
+  (`grep "^export\|^function\|^class"`) rather than full-text-grepping it again.
+  Repeated grep on a large barrel burns the turn budget and risks the agent
+  returning *before* it synthesizes its report.
 - **Git**: no hard budget.
 
 ## Fallback rules
@@ -80,6 +89,11 @@ Before picking a tier, classify the query:
 - LSP returns zero references for a symbol you know exists → fall back to
   Grep; the symbol may live in a file the LSP server hasn't indexed yet (e.g.
   a path excluded by `tsconfig.json`).
+- LSP is off **and** Grep cannot locate a symbol's definition (it lives in a
+  barrel / re-export file, or grep keeps missing) → the code graph is a valid
+  fallback for *locating* it: `graphify explain "<symbol>"` / `graphify query`
+  (when `features.has_code_graph: true`). Do not keep grepping — see the per-symbol
+  cap in **Budget** above.
 - LSP times out (>8s) → fall back to Grep for this query, log the symptom in
   the agent's reasoning so the user can re-run doctor.
 - **Cold start under-reporting**: the first LSP query in a session can return

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.52.2",
+  "version": "4.52.4",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"