baldart 4.84.0 → 4.86.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.86.0] - 2026-07-01
+
+**AGENTS.md primitive regains the universal working-discipline rules (primitive `1.2.0`).** The lean v4.83.0 rewrite of the skeleton dropped a handful of everyday-habit MUSTs to stay short — but those are exactly the "conventions an agent can't infer and gets wrong" the file exists to carry. Restored as compact, stack-agnostic rules in the `AGENTS.md` skeleton (the cross-tool SSOT):
+
+- **File navigation**: MUST find real paths via Glob/Grep before reading — never guess a path from naming conventions.
+- **Investigation before claiming**: check git history (`git log --all --grep`) + the actual source before asserting a feature does or does not exist.
+- **Implementation completeness**: MUST verify every plan item / acceptance criterion is wired and functional before marking work DONE — cross-check against the code, not the intent.
+- **Testing convention** (Workflow Gates): when a test fails, fix the *code* not the test (unless the test is wrong); for a new feature, write the failing test first.
+
+**MINOR** — enriches shipped skeleton content; no config key, no CLI/layout change; contamination-clean (no project tokens). Consumers pick it up on the next `npx baldart update` (byte-stable on everything else; adopted overlays untouched). `primitive_version` (AGENTS) 1.1.0 → 1.2.0; CLAUDE stub unchanged (1.1.0).
+
+### Changed
+
+- **`framework/templates/primitives/AGENTS.md`** — added the file-navigation + investigation + implementation-completeness MUSTs and the testing convention in Workflow Gates. `primitive_version` → 1.2.0.
+- **`framework/templates/primitives/AGENTS.CHANGELOG.md`** — `1.2.0` entry.
+
+## [4.85.0] - 2026-07-01
+
+**Root-file primitives gain universal delegation + quality rules (primitive `1.1.0`).** The v4.83.0 skeletons pointed to `.claude/agents/REGISTRY.md` for agent routing but never stated the single highest-frequency rule in the always-loaded file: *which agent writes what*. The `AGENTS.md` primitive (the cross-tool SSOT Codex also reads) now carries a **MUST**: plan-and-delegate, never write substantial code inline — **code / logic / tests → `coder`**, **UI → `ui-expert`** (dual-tool: Claude Task `subagent_type` / Codex custom agent by name; every other agent routes via `REGISTRY.md`). The `CLAUDE.md` stub's Plan Mode names both agents to match (was `coder` only).
+
+Alongside it, the **universal, stack-agnostic** subset of rules a mature project accumulates — previously discoverable only after a project authored them by hand — is promoted into the skeleton: a **security-hygiene MUST** (no hardcoded secrets, no exposed stack traces, no PII in logs, validate/parse external inputs), a **Quality bar (SHOULD)** (bound/paginate list queries — no unbounded/N+1 — + Core Web Vitals for web UIs + baseline accessibility), and explicit **worktree isolation** in the Git Workflow (new branch → `/nw`; never `git switch`/`checkout -b`/`branch` on the shared main checkout). **Deliberately NOT promoted** (they stay project overlay, and would trip the contamination scanner): exact KPI numbers, database/ORM specifics, CSS-framework choices, and project-specific git rituals.
+
+**MINOR** — enriches the shipped skeleton's protocol content; no new `baldart.config.yml` key, no layout/CLI change. Consumers pick it up on the next `npx baldart update` (the writer regenerates `AGENTS.md`/`CLAUDE.md`, byte-stable on everything else). `primitive_version` 1.0.0 → 1.1.0.
+
+### Changed
+
+- **`framework/templates/primitives/AGENTS.md`** — added the implementation-delegation MUST (`coder`/`ui-expert`), the security-hygiene MUST, a `## Quality bar (SHOULD)` section (performance + accessibility), and worktree isolation in Git Workflow. `primitive_version` → 1.1.0.
+- **`framework/templates/primitives/CLAUDE.md`** — Plan Mode delegation now names `coder` (code) + `ui-expert` (UI) + `doc-reviewer` (docs). `primitive_version` → 1.1.0.
+- **`framework/templates/primitives/AGENTS.CHANGELOG.md` + `CLAUDE.CHANGELOG.md`** — `1.1.0` entries.
+
 ## [4.84.0] - 2026-07-01
 
 **`/ds-handoff` decision & preference pass — anticipa le domande di Claude Design invece di rimandargliele.** Il prompt field-level di `ds-handoff` copriva un solo asse (correttezza dei *campi* via field-extraction + coverage gate) e lasciava scoperto il **secondo asse — le decisioni di design aperte + le preferenze di consegna** — che è esattamente ciò su cui Claude Design rimanda le domande all'utente (nel caso reale "Hub fornitore", 6 domande su 6 erano su questo asse, zero sui campi). Una era **auto-inflitta** (il PRD diceva *"da proporre"* e la skill l'ha inoltrata testualmente), un'altra su un fatto **già in mano alla skill** (enum categoria con `color`) mai tradotto in istruzione.

package/VERSION

@@ -1 +1 @@
-4.84.0
+4.86.0

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

@@ -4,6 +4,36 @@ 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.2.0 — 2026-07-01
+
+- Restored the universal **working-discipline** rules the lean v1.0.0 rewrite had dropped
+  (they prevent concrete, recurring failures and are exactly the "conventions an agent
+  can't infer" the file should carry):
+  - MUST find real paths via Glob/Grep before reading — never guess from naming; check git
+    history + source before claiming a feature exists or not.
+  - MUST verify every plan item / acceptance criterion is wired + functional before DONE
+    (cross-check against code, not intent).
+  - Testing convention in Workflow Gates: fix the **code** not the test (unless the test is
+    wrong); for a new feature, write the failing test first.
+- All stack-agnostic; no project tokens (contamination-clean).
+
+## 1.1.0 — 2026-07-01
+
+- **Implementation-delegation MUST**: plan-and-delegate, never write substantial code
+  inline — **code/logic/tests → `coder`**, **UI → `ui-expert`** (dual-tool: Claude Task
+  `subagent_type` / Codex by-name); other agents route via `.claude/agents/REGISTRY.md`.
+  Now in the cross-tool SSOT so Codex sees it too (was only weakly in the CLAUDE.md stub).
+- **Universal security hygiene MUST**: no hardcoded secrets, no exposed stack traces, no
+  PII in logs, validate/parse external inputs at the boundary.
+- **Quality bar (SHOULD)**: stack-agnostic performance discipline (no unbounded/N+1 list
+  reads, Core Web Vitals) + baseline accessibility. Project-specific KPI numbers stay in
+  the overlay.
+- **Git Workflow**: explicit worktree isolation — new branch → `/nw`; orchestrator never
+  runs `git switch`/`checkout -b`/`branch` on the shared main checkout.
+- Distilled the UNIVERSAL subset of common project rules; stack-specific specifics
+  (database/ORM & migration policies, CSS-framework choices, exact KPI numbers, git
+  rituals) remain overlay content, never baked into the shipped skeleton.
+
 ## 1.0.0 — 2026-07-01
 
 - Primo skeleton SOTA cross-tool (framework v4.83.0). Sostituisce il bulk symlink di

package/framework/templates/primitives/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- baldart-primitive: name=AGENTS primitive_version=1.0.0
+<!-- baldart-primitive: name=AGENTS primitive_version=1.2.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,
@@ -28,6 +28,12 @@ mechanics — this file remains the single source of truth for the protocol.
   (Claude Code: Task tool `subagent_type: codebase-architect`; Codex: the custom agent by
   name at `.codex/agents/codebase-architect.toml`). Only if NEITHER mechanism exists,
   degrade explicitly to inline retrieval (code-graph → LSP → Grep) and SAY SO.
+- MUST delegate implementation to the domain agent — plan and delegate, do NOT write
+  substantial code inline: **code / logic / tests → `coder`**; **UI (components, pages,
+  styling, visual output) → `ui-expert`**. Same dual-tool invocation as `codebase-architect`
+  (Claude Code: Task tool `subagent_type`; Codex: custom agent by name). Every other agent
+  (code-reviewer, doc-reviewer, qa-sentinel, security-reviewer, …) routes via
+  `.claude/agents/REGISTRY.md`.
 - MUST NOT silently substitute a different agent when an invocation returns empty / times
   out / is denied — STOP, report verbatim, and wait. Never auto-route to a generic agent.
 - MUST NOT work on files another agent has claimed; parallel work only on independent areas.
@@ -43,6 +49,13 @@ mechanics — this file remains the single source of truth for the protocol.
   directly to `{{ git.trunk_branch }}` — all changes reach it via PR.
 - MUST get owner approval before force-push/reset or deleting an UNMERGED branch (create a
   `backup/<YYYYMMDD>-<reason>` tag first). Deleting an already-merged branch is routine.
+- MUST NOT hardcode secrets / tokens / API keys (env vars only), expose internal stack
+  traces in responses, or log PII. Validate & parse every external / user input at the boundary.
+- MUST find real file paths via Glob/Grep before reading — never guess a path from naming
+  conventions. Check git history (`git log --all --grep`) and the actual source before
+  claiming a feature does or does not exist.
+- MUST verify every plan item / acceptance criterion is wired and functional before marking
+  work DONE — cross-check each against the code, not the intent.
 - MUST run the testing gates before DONE (see § Workflow Gates).
 
 **Feature-gated (active only when the flag is `true` in `baldart.config.yml`):**
@@ -72,7 +85,9 @@ mechanics — this file remains the single source of truth for the protocol.
 Branch naming: `{{ git.feature_prefix }}/<CARD-ID>-slug` (local), `codex/…` or `claude/…`
 (cloud agents), `hotfix/<ID>-slug` (production fixes). Branches are created by the
 orchestrator (`/nw`, `/new`) or the user — **never by the `coder` agent** (it implements on
-the branch it was spawned on). Stage explicit filenames only; never bundle unrelated changes.
+the branch it was spawned on). For a NEW branch, prefer a git **worktree** (`/nw`): the
+orchestrator MUST NOT run `git switch` / `checkout -b` / `branch` on the shared main
+checkout (other sessions share it). Stage explicit filenames only; never bundle unrelated changes.
 
 ## Workflow Gates
 
@@ -83,6 +98,17 @@ run a full build every commit.
 **Pre-PR (once, before opening a PR):** full build (must pass) · unit tests (if they exist) ·
 E2E for critical-flow changes.
 
+When a test fails, fix the **code**, not the test — unless the test itself is wrong. For a
+new feature with tests, prefer writing the failing test first, then the minimum code to pass.
+
+## Quality bar (SHOULD)
+
+- SHOULD respect performance budgets — avoid unbounded or N+1 data access on list paths
+  (bound + paginate queries, index hot lookups), and for web UIs keep Core Web Vitals
+  healthy (LCP / INP / CLS). Project-specific numeric targets live in the overlay.
+- SHOULD meet baseline accessibility for interactive UI — keyboard navigation, sufficient
+  contrast, labelled inputs, alt text on informative images.
+
 ## Execution Modes
 
 | Mode | Branch | Validation |

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

@@ -4,6 +4,12 @@ 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.1.0 — 2026-07-01
+
+- Plan Mode delegation now names **both** domain agents — **code → `coder`**, **UI →
+  `ui-expert`** (was `coder` only) — plus `doc-reviewer` for full docs/SSOT. Mirrors the
+  new cross-tool delegation MUST in the AGENTS.md primitive.
+
 ## 1.0.0 — 2026-07-01
 
 - Primo stub Claude-native (framework v4.83.0). BALDART inizia a spedire `CLAUDE.md`.

package/framework/templates/primitives/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- baldart-primitive: name=CLAUDE primitive_version=1.0.0
+<!-- baldart-primitive: name=CLAUDE primitive_version=1.1.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.
@@ -19,8 +19,9 @@ SSOT, not restated here. Below are the **Claude-native mechanics only**.
 - Invoke `codebase-architect` before writing the plan — never plan blind.
 - Launch `plan-auditor` + `doc-reviewer` in parallel to review the plan, incorporate their
   feedback, and state inside the plan that the review gate was honored, BEFORE `ExitPlanMode`.
-- Wait for explicit user approval, then delegate implementation to the `coder` agent (via the
-  Task tool). The `coder` writes code + minimal doc stubs only.
+- Wait for explicit user approval, then delegate implementation to the domain agent via the
+  Task tool — **code / logic / tests → `coder`**, **UI → `ui-expert`**. Each writes code +
+  minimal doc stubs only; full docs / SSOT sync go to `doc-reviewer`.
 
 ## User Interaction (Claude-native, ABSOLUTE)
 

package/package.json

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