baldart 4.98.0 → 4.98.2

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.98.2] - 2026-07-02
+
+**Negative guard: the codebase-understanding step is `codebase-architect`, not the generic built-in search agent.** A third live session — a data-wiring task (replace a hardcoded `"unità"` label with the real unit-of-measure in an order-wizard `ProductRow`) — delegated the code-path trace to the built-in `Explore` agent instead of `codebase-architect`, bypassing the profile engine, Reuse Analysis, Canonical Evidence, and the Return Contract. Diagnosed carefully (and deliberately *not* over-fitted): this was **not** a `PROFILE=ui` miss — the task's substance is data/logic wiring (product → UoM → loader → label), whose fitting profile is `feature`, not `ui`; the profile axis was left untouched. The real deviation was on the **agent-selection** axis, and it matches the recurring v4.97.1 shape: a positive mandate ("invoke `codebase-architect`") with no explicit "and NOT the generic explorer" guard (the existing `AGENTS.md` "never auto-route to a generic agent" rule is scoped to the *failure-fallback* case, not the initial choice).
+
+- `AGENTS.md` primitive `1.7.1 → 1.7.2` (§ Non-negotiables): the understanding step goes through `codebase-architect` with the matching profile — **not the generic built-in search / `general-purpose` agent** (runtime-generic phrasing for cross-tool parity).
+- `CLAUDE.md` primitive `1.4.1 → 1.4.2` (§ Subagents): names the Claude-native built-in explicitly — use `subagent_type: codebase-architect` + `PROFILE`, **not `Explore` / `general-purpose`**; `Explore` stays fine for a throwaway file-location grep, never for grounding.
+
+**PATCH** — one-clause guard, no new surface, no config key, no install-layout change. The `ui`-vs-`feature` profile refinement (a UI-*framed* but data-*substance* task should route `feature`/`impact`, not `ui`) was **considered and deferred** to avoid churn on the just-stabilized v4.98.0/1 rule. **Codex parity: portable** — AGENTS.md carries the runtime-generic guard, CLAUDE.md names the built-in. **Not a `baldart.config.yml` key** → the schema-change propagation rule does NOT apply.
+
+## [4.98.1] - 2026-07-02
+
+**UI *verification* also routes `PROFILE=ui`, not just UI *change* — closing the one gap v4.98.0 missed.** A live post-update session confirmed v4.98.0 works where it matters: on the actual change ("migriamo") Claude correctly spawned `codebase-architect (PROFILE=ui)`. The only borderline case was the *preceding* verification ("mi verifichi che /products/new su desktop e tablet sia già sul nuovo page layout") — answered with an inline Grep. Root cause was in the v4.98.0 wording itself: the UI grounding mandate was scoped entirely to the verb "change/build", so a literal reader treated a read-only UI verification as outside it. Fixed by broadening "any UI **change**" to "any UI **work** — a change OR a verification/question whose correct answer needs design-system-spec or responsive/state grounding" across the same three surfaces:
+
+- `AGENTS.md` primitive `1.7.0 → 1.7.1` (§ Non-negotiables + § Change Tiers carve-out + Light bullet), `CLAUDE.md` primitive `1.4.0 → 1.4.1` (Plan Mode paragraph).
+- `agents/analysis-profiles.md`: no-token inference rule #1 now includes "verifying/inspecting the design-system adoption or responsive state of" a component/page/layout; § 3 routing row broadened to "ad-hoc UI change OR adoption/responsive verification outside a skill → `ui`".
+- **A bare symbol-presence check** ("does file X import Y" — a pure Grep, no correctness/responsive judgment) is now explicitly exempt alongside the Trivial one-liner, so narrow lookups keep their fast path and the proportionality concern (no full architect spawn for a yes/no import check) is respected.
+
+**PATCH** — same-day refinement of the v4.98.0 rule, no new surface, no config key, no install-layout change. **Codex parity: portable** — pure prose in the shared skeleton + the `agents/` module both runtimes read. **Not a `baldart.config.yml` key** → the schema-change propagation rule does NOT apply.
+
 ## [4.98.0] - 2026-07-02
 
 **Codebase understanding is tier-orthogonal — and every UI change grounds via `PROFILE=ui`, even a "quick" one.** A live Claude session took a small ad-hoc UI request ("modifichiamo al volo questa pagina su desktop e tablet, serve il back button sull'header") and went straight to `find`/`grep`/`Read` instead of spawning `codebase-architect` with `PROFILE=ui` — whereas Codex, on the same framework, routes the profile correctly. An adversarial pass (3 skeptics) **refuted the obvious diagnosis** ("Codex reads a stricter doc than Claude"): `CLAUDE.md` states AGENTS.md is loaded automatically alongside it, so Claude reads the *same* unconditional `codebase-architect` MUST that Codex reads — this was a Claude-side *misreading* of an already-universal rule, not a weaker rule. The real drivers, confirmed with `path:line`:

package/VERSION

@@ -1 +1 @@
-4.98.0
+4.98.2

package/framework/agents/analysis-profiles.md

@@ -30,8 +30,10 @@ instead of restating search strategy).
   never read this module end-to-end.
 - **No token → deterministic inference**, in this exact priority order (first match wins):
   1. prompt concerns UI — a mockup / `links.design` / `component_bindings` / design-system
-     registry / tokens, OR building or changing a component, page, header, layout, styling,
-     or responsive/breakpoint behavior → `ui`
+     registry / tokens, OR building, changing, OR **verifying/inspecting the design-system
+     adoption or responsive state of** a component, page, header, layout, styling, or
+     responsive/breakpoint behavior → `ui`. (A bare symbol-presence check — "does file X
+     import Y" — is a plain Grep, not this profile.)
   2. prompt asks blast-radius / affected surface / "what depends on" / refactor scope →
      `impact`
   3. prompt reports an error / crash / regression / "non funziona" → `bug`
@@ -189,7 +191,7 @@ payload should never rely on `full` — pass a token.
 
 | Caller | Profile |
 |---|---|
-| ad-hoc UI change outside a skill (component / page / header / styling / responsive) | `ui` |
+| ad-hoc UI change OR adoption/responsive verification outside a skill (component / page / header / styling / responsive) | `ui` |
 | ad-hoc pre-implementation grounding outside a skill (non-UI) | `feature` |
 | `/new` implement.md Phase 1 step 3 · `new2.js` B7 | `ui` if card has non-empty `links.design` OR `links.design_src` (the `hasMockup` bit), else `feature` |
 | `new-final-review.js` / `new-card-review.js` Phase Baseline · `/codexreview` Step 1 | `baseline` |

package/framework/templates/primitives/AGENTS.CHANGELOG.md

@@ -4,6 +4,34 @@ Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://sem
 Questo è il changelog INTERNO dello skeleton spedito (`primitive_version`), separato dal
 file `AGENTS.md` generato nel consumer e indipendente dal `VERSION` del framework.
 
+## 1.7.2 — 2026-07-02
+
+- **Negative guard: the understanding step is `codebase-architect`, NOT a generic search
+  agent.** A live session on a data-wiring task (replace a hardcoded `"unità"` with the real
+  unit-of-measure in an order-wizard row) delegated the code-path trace to the generic
+  built-in `Explore` agent instead of `codebase-architect` — bypassing the profile engine,
+  Reuse Analysis, Canonical Evidence, and the Return Contract. Root cause is the recurring
+  v4.97.1 shape: a positive mandate ("invoke `codebase-architect`") with no explicit "and NOT
+  the generic explorer" guard (the existing "never auto-route to a generic agent" rule is
+  scoped to the *fallback* case, not the initial choice). The § Non-negotiables MUST now
+  states the understanding step goes through `codebase-architect` with the matching profile —
+  **not the generic built-in search / `general-purpose` agent**. Portable (Claude + Codex);
+  the profile axis was deliberately left untouched (this task's fitting profile is `feature`,
+  a data-wiring trace — not `ui`).
+
+## 1.7.1 — 2026-07-02
+
+- **UI *verification* also routes `PROFILE=ui`, not just UI *change*** (follow-up to 1.7.0).
+  1.7.0 scoped the UI grounding mandate entirely to "change/build", so a read-only UI
+  verification ("is page X already on the new layout, on desktop and tablet?") fell in a gap
+  and a literal reader answered it with an inline Grep. Now the mandate reads "any UI **work**"
+  — a change OR a **verification/question whose correct answer needs design-system-spec or
+  responsive/state grounding**. A **bare symbol-presence check** ("does file X import Y" — a
+  pure Grep, no correctness/responsive judgment) stays explicitly exempt alongside the Trivial
+  one-liner, so narrow lookups keep their fast path. Verified against a live session: the fix
+  correctly fired the architect on the *change* ("migriamo"); only the initial *verification*
+  was uncovered — this closes it. Portable (Claude + Codex).
+
 ## 1.7.0 — 2026-07-02
 
 - **Codebase understanding is tier-orthogonal, and UI work always grounds via `PROFILE=ui`**:

package/framework/templates/primitives/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- baldart-primitive: name=AGENTS primitive_version=1.7.0
+<!-- baldart-primitive: name=AGENTS primitive_version=1.7.2
      This is the SHIPPED SKELETON. The writer (src/utils/root-primitives.js) strips
      this banner, resolves every {{ slot }} / {{> partial }} / {{#flag}} from
      baldart.config.yml (+ package.json/README), merges .baldart/overlays/AGENTS.md,
@@ -32,10 +32,17 @@ mechanics — this file remains the single source of truth for the protocol.
   context) · `ui` (design-system / component scope) · `baseline` (review grounding over a
   diff). Contract + per-profile scoping: `agents/analysis-profiles.md`. This applies
   **regardless of tier** (§ Change Tiers): a **Light** change still grounds first whenever
-  acting correctly needs understanding you don't already have, and **any UI change routes
-  `PROFILE=ui`** (design-system / component grounding) even for a small tweak. Only a genuine
-  **Trivial** one-liner — a typo or an obvious self-contained fix — skips it; starting with an
-  inline Grep is NOT a substitute when the change needs cross-file or design-system grounding.
+  acting correctly needs understanding you don't already have, and **any UI work routes
+  `PROFILE=ui`** (design-system / component grounding) even for a small tweak — a change, OR a
+  **verification/question** whose correct answer needs design-system-spec or responsive/state
+  grounding (e.g. "is page X already on the new layout, on desktop and tablet?"). Only a genuine
+  **Trivial** one-liner (a typo, an obvious self-contained fix) or a **bare symbol-presence
+  check** (does file X import Y — a pure Grep, no correctness/responsive judgment) skips it;
+  starting with an inline Grep is NOT a substitute when the task needs cross-file or
+  design-system grounding. The understanding step goes through `codebase-architect` (with the
+  matching profile) — **NOT the generic built-in search / `general-purpose` agent**, which
+  lacks the profile engine, Reuse Analysis, Canonical Evidence, and the Return Contract; that
+  is the agent to invoke, not a generic explorer.
   Only if NEITHER invocation mechanism exists, degrade explicitly to inline retrieval
   (code-graph → LSP → Grep) and SAY SO.
 - MUST have any **Heavy** plan (see § Change Tiers) reviewed BEFORE presenting it for
@@ -106,14 +113,16 @@ machinery (plan mode, plan review, delegation, worktree, backlog card) applies.
 doubt, treat it as Light** and escalate only when a Heavy trigger is actually present.
 **Codebase understanding (`codebase-architect` + the matching profile, § Non-negotiables) is
 NOT part of this tier-gated machinery** — it precedes the tier decision and applies to Light
-too; only a Trivial one-liner skips it, and any UI change always grounds via `PROFILE=ui`.
+too; only a Trivial one-liner or a bare symbol-presence Grep skips it, and any UI work —
+change OR a spec/responsive-grounded verification — always grounds via `PROFILE=ui`.
 
 - **Trivial** — a one-liner, typo, or obvious bug with a clear fix. Just do it.
 - **Light** — the default for most work. Any change that does **not** hit a Heavy trigger,
   even if it spans several files within one coherent area. → Implement **directly on the
   current branch**: no plan mode, no plan-review gate, no worktree, no backlog card. The
   orchestrator may edit inline or delegate for volume, but **still grounds via
-  `codebase-architect` first** when the change needs real understanding (UI → `PROFILE=ui`).
+  `codebase-architect` first** when the task needs real understanding (UI work — change or
+  spec/responsive-grounded verification → `PROFILE=ui`).
   Docs stay in sync and the pre-commit gates still run.
 - **Heavy** — escalate ONLY when the change: introduces a new DB schema / migration; adds a
   new external dependency; adds a new API contract / route or a new domain entity; is a wide

package/framework/templates/primitives/CLAUDE.CHANGELOG.md

@@ -4,6 +4,24 @@ Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://sem
 Changelog INTERNO dello stub spedito (`primitive_version`), separato dal `CLAUDE.md`
 generato nel consumer e indipendente dal `VERSION` del framework.
 
+## 1.4.2 — 2026-07-02
+
+- **Name the built-in `Explore` guard for the understanding step**: § Subagents now says the
+  codebase-understanding step uses `subagent_type: codebase-architect` + the matching `PROFILE`,
+  **not the built-in `Explore` / `general-purpose` search agent** (those return raw excerpts;
+  only `codebase-architect` runs the profile engine / Reuse Analysis / Canonical Evidence /
+  Return Contract). `Explore` stays fine for a throwaway file-location grep. Mirrors AGENTS
+  primitive 1.7.2 (which phrases the guard runtime-generically for cross-tool parity).
+
+## 1.4.1 — 2026-07-02
+
+- **UI verification also grounds via `PROFILE=ui`** (follow-up to 1.4.0): the Plan Mode
+  paragraph now says "every UI **task**" grounds — a change OR a verification/question whose
+  correct answer needs design-system-spec or responsive/state grounding — with a bare
+  symbol-presence check ("does file X import Y") explicitly exempt. Mirrors AGENTS primitive
+  1.7.1. Closes the gap where a read-only "is page X on the new layout?" was answered by an
+  inline Grep because 1.4.0 mandated grounding only on UI *changes*.
+
 ## 1.4.0 — 2026-07-02
 
 - **Break the "Light skips delegation → Light skips architect" conflation**: the Plan Mode

package/framework/templates/primitives/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- baldart-primitive: name=CLAUDE primitive_version=1.4.0
+<!-- baldart-primitive: name=CLAUDE primitive_version=1.4.2
      SHIPPED SKELETON. The writer strips this banner, resolves {{ slot }}/{{#flag}} from
      baldart.config.yml, merges .baldart/overlays/CLAUDE.md, stamps a baldart-generated
      marker, and writes the result to the repo root.
@@ -19,8 +19,11 @@ Plan mode is for **Heavy** changes only (see `AGENTS.md` § Change Tiers). **Lig
 them directly. When in doubt, treat it as Light. They do **NOT**, however, skip codebase
 understanding: the `codebase-architect` + `PROFILE` invocation (`AGENTS.md` § Non-negotiables)
 is **tier-orthogonal** — a Light change still grounds via it whenever acting correctly needs
-understanding you don't already have, and **every UI change grounds via `PROFILE=ui`** even for
-a small tweak. Only a genuine Trivial one-liner skips it. For a Heavy task:
+understanding you don't already have, and **every UI task grounds via `PROFILE=ui`** — a change,
+OR a verification/question whose correct answer needs design-system-spec or responsive/state
+grounding (e.g. "is page X already on the new layout, on desktop and tablet?") — even for a small
+tweak. Only a genuine Trivial one-liner or a bare symbol-presence check (does file X import Y)
+skips it. For a Heavy task:
 
 - Enter plan mode (`EnterPlanMode`) before writing code.
 - Invoke `codebase-architect` before writing the plan — never plan blind. Pass the
@@ -42,6 +45,11 @@ a small tweak. Only a genuine Trivial one-liner skips it. For a Heavy task:
 
 - Spawn subagents via the Task tool (`subagent_type: <name>`); the roster + routing is
   `.claude/agents/REGISTRY.md`.
+- For the **codebase-understanding step** (`AGENTS.md` § Non-negotiables) use
+  `subagent_type: codebase-architect` with the matching `PROFILE` — **not the built-in
+  `Explore` / `general-purpose` search agent**. Those return raw excerpts; only
+  `codebase-architect` runs the profile engine, Reuse Analysis, Canonical Evidence, and the
+  Return Contract. `Explore` is fine for a throwaway file-location grep, never for grounding.
 {{#output_style}}
 - Output style: `{{ output_style }}` is active (select via `/config` → Output Style).
 {{/output_style}}

package/package.json

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