baldart 4.97.1 → 4.98.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.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`:
+
+- **`CLAUDE.md` conflated "Light skips plan mode / delegation" with "Light skips understanding."** The architect + `PROFILE` bullet lived *only* inside the "For a Heavy task:" block, so a Light-task reader treated grounding as Heavy-only machinery. Fixed: the Plan Mode section now states the invocation is **tier-orthogonal** and applies to Light too; UI → `PROFILE=ui` always; only a genuine Trivial one-liner skips it. (CLAUDE primitive `1.3.0 → 1.4.0`.)
+- **`AGENTS.md` § Change Tiers never carved understanding out of the tier-gated "heavy machinery" list**, so it got swept into the Light exemption by association. Fixed: § Non-negotiables now says the architect MUST applies **regardless of tier** (UI → `PROFILE=ui`, Trivial one-liner exempt, inline Grep is not a substitute); § Change Tiers explicitly excludes understanding from the tier-gated machinery; the Light bullet reiterates it grounds first when the change needs real understanding. (AGENTS primitive `1.6.0 → 1.7.0`.)
+- **The "which profile, when" mapping for ad-hoc UI requests lived only in `/new` `implement.md`**, so a request *outside any skill* had no routing rule. Fixed in `agents/analysis-profiles.md`: the no-token inference rule #1 now catches generic UI work (component / page / header / layout / styling / responsive), not just a named mockup; and the § 3 routing table gains explicit rows for **ad-hoc UI change outside a skill → `ui`** and ad-hoc non-UI grounding → `feature`.
+
+The hook-based enforcement one skeptic proposed (a `PreToolUse` gate that blocks edits until architect ran) was **rejected**: it can't distinguish a typo from a UI change, would block Trivial one-liners and follow-up edits, and reproduces the already-refuted "do-X-every-time gate without a ground truth" antipattern (v4.78.2). The Trivial exemption is preserved throughout, so genuine one-liners keep their fast path — no latency regression.
+
+**MINOR** — shipped-primitive behavior clarification (regenerated into consumers on `baldart update`); no new surface, no config key, no install-layout change. **Codex parity: portable** — pure prose in the shared skeleton + the bulk-symlinked `agents/` module both runtimes read; AGENTS.md is the cross-tool SSOT (already correct, now unambiguous), CLAUDE.md is the Claude-native stub where the regression lived. **Not a `baldart.config.yml` key** → the schema-change propagation rule does NOT apply.
+
 ## [4.97.1] - 2026-07-02
 
 **`/ds-new` + `/ds-edit`: locate/reuse-first is a deterministic registry lookup, never a search agent.** A live `/ds-edit` run went off-script — instead of the skill's deterministic spine (resolve the component spec → `ui-expert` source edit → `extract-one` → `serialize-spec` → `doc-reviewer` → `ds-gate`), the model improvised ad-hoc `general-purpose` agents to "find" the component and verify a formatter. Root cause: the skills said *what* to do ("resolve the existing component") but never forbade *how not to*. Reaffirmed (adversarially) that the v4.94.0 `codebase-architect` analysis profiles correctly do NOT belong in the `ds*` skills — those operate on a single, already-named element (no scope→registry fan-out), and `ds-new`'s reuse-first is a **deterministic signature detector** that an LLM `ui`-profile pass would only make fuzzier and duplicate; the `ui` profile lives in the *planning* skills (`/prd`, `/ui-design`, `/new`, `/ds-handoff`, `context-primer`) and, when it matters, already ran upstream before `/prd` delegates to `ds-new`/`ds-edit`.

package/VERSION

@@ -1 +1 @@
-4.97.1
+4.98.0

package/framework/agents/analysis-profiles.md

@@ -29,8 +29,9 @@ instead of restating search strategy).
   `### PROFILE: <name>` and Read ONLY that section (plus any `§ Shared block` it cites) —
   never read this module end-to-end.
 - **No token → deterministic inference**, in this exact priority order (first match wins):
-  1. prompt names a mockup / `links.design` / `component_bindings` / design-system
-     registry / tokens → `ui`
+  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`
   2. prompt asks blast-radius / affected surface / "what depends on" / refactor scope →
      `impact`
   3. prompt reports an error / crash / regression / "non funziona" → `bug`
@@ -188,6 +189,8 @@ 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 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` |
 | `plan-auditor` FULL-mode grounding spawn | `impact` |

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.0 — 2026-07-02
+
+- **Codebase understanding is tier-orthogonal, and UI work always grounds via `PROFILE=ui`**:
+  the `codebase-architect` + profile MUST (§ Non-negotiables) now states explicitly that it
+  applies **regardless of tier** — a **Light** change still grounds first whenever acting
+  correctly needs understanding, and **any UI change routes `PROFILE=ui`** even for a small
+  tweak; only a genuine **Trivial** one-liner skips it, and an inline Grep is not a substitute.
+  § Change Tiers now carves understanding **out** of the tier-gated "heavy machinery" list
+  (it precedes the tier decision), and the Light bullet reiterates "still grounds via
+  `codebase-architect` first when the change needs real understanding (UI → `PROFILE=ui`)".
+  Closes the gap where an ad-hoc "quick" UI edit (outside any skill) skipped the architect
+  because the reader conflated "Light skips plan mode / delegation" with "Light skips
+  understanding". Cross-tool: pure prose in the shared skeleton — portable (both runtimes read
+  the same MUST; this was a Claude-side misreading of an already-universal rule, now unambiguous).
+
 ## 1.6.0 — 2026-07-02
 
 - **Change Tiers — a real Light lane between Trivial and Heavy**: new `## Change Tiers`

package/framework/templates/primitives/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- baldart-primitive: name=AGENTS primitive_version=1.6.0
+<!-- baldart-primitive: name=AGENTS primitive_version=1.7.0
      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,
@@ -30,8 +30,13 @@ mechanics — this file remains the single source of truth for the protocol.
   profile**: `PROFILE=feature` (pre-implementation grounding) · `bug` (failure-path
   tracing) · `impact` (blast radius / refactor scope) · `discovery` (planning / question
   context) · `ui` (design-system / component scope) · `baseline` (review grounding over a
-  diff). Contract + per-profile scoping: `agents/analysis-profiles.md`. Only if NEITHER
-  invocation mechanism exists, degrade explicitly to inline retrieval
+  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.
+  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
   approval — run `plan-auditor` + `doc-reviewer` (in parallel), incorporate their feedback,
@@ -99,13 +104,17 @@ mechanics — this file remains the single source of truth for the protocol.
 Every change is one of three tiers. The tier — NOT raw file count — decides whether the heavy
 machinery (plan mode, plan review, delegation, worktree, backlog card) applies. **When in
 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`.
 
 - **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. Docs stay in sync and the pre-commit
-  gates still run.
+  orchestrator may edit inline or delegate for volume, but **still grounds via
+  `codebase-architect` first** when the change needs real understanding (UI → `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
   or cross-module refactor; or runs in parallel with other agents/sessions on shared files.

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

@@ -4,6 +4,17 @@ 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.0 — 2026-07-02
+
+- **Break the "Light skips delegation → Light skips architect" conflation**: the Plan Mode
+  section now states that Light/Trivial changes skip plan mode / plan-review / mandatory
+  delegation but do **NOT** skip codebase understanding — the `codebase-architect` + `PROFILE`
+  invocation is **tier-orthogonal**, a Light change still grounds via it when acting correctly
+  needs understanding, and **every UI change grounds via `PROFILE=ui`**; only a genuine Trivial
+  one-liner skips it. This was the Claude-native locus of the bug: the architect bullet lived
+  only inside the "For a Heavy task:" block, so a Light-task reader treated it as Heavy-only.
+  Mirrors the AGENTS.md primitive 1.7.0 § Non-negotiables / § Change Tiers clarification.
+
 ## 1.3.0 — 2026-07-02
 
 - Plan Mode scoped to **Heavy** changes (see `AGENTS.md` § Change Tiers): Light and Trivial

package/framework/templates/primitives/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- baldart-primitive: name=CLAUDE primitive_version=1.3.0
+<!-- baldart-primitive: name=CLAUDE primitive_version=1.4.0
      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.
@@ -16,7 +16,11 @@ SSOT, not restated here. Below are the **Claude-native mechanics only**.
 
 Plan mode is for **Heavy** changes only (see `AGENTS.md` § Change Tiers). **Light** and
 **Trivial** changes skip plan mode, the plan-review gate, and mandatory delegation — implement
-them directly. When in doubt, treat it as Light. For a Heavy task:
+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:
 
 - Enter plan mode (`EnterPlanMode`) before writing code.
 - Invoke `codebase-architect` before writing the plan — never plan blind. Pass the

package/package.json

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