baldart 4.98.1 → 4.98.2

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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:

package/VERSION

@@ -1 +1 @@
-4.98.1
+4.98.2

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

@@ -4,6 +4,21 @@ 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).

package/framework/templates/primitives/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- baldart-primitive: name=AGENTS primitive_version=1.7.1
+<!-- 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,
@@ -39,7 +39,10 @@ mechanics — this file remains the single source of truth for the protocol.
   **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.
+  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

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

@@ -4,6 +4,15 @@ 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

package/framework/templates/primitives/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- baldart-primitive: name=CLAUDE primitive_version=1.4.1
+<!-- 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.
@@ -45,6 +45,11 @@ 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.1",
+  "version": "4.98.2",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"