baldart 4.56.3 → 4.57.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.57.0] - 2026-06-20
+
+**`coder` now prevents the avoidable code smells at authoring time — an author-time subset of the `simplify` taxonomy applied WHILE writing — without removing the independent `simplify` review pass.** Triggered by a user question: "can we save ourselves the `simplify` agent by folding its job into the `coder` as prevention, avoiding the double pass?" An extensive review (codebase + scientific literature, then an adversarial pass) established that the "double pass = redundant" framing is a trap: the two passes are **complementary, not redundant**, and removing the independent one is the risky half.
+
+The evidence cut both ways and shaped a **hybrid** outcome (the user's choice over full elimination):
+
+- **For prevention (sound):** LLM-authored code carries measurably more code smells than human reference solutions (+63% average, Codex +85% — [arXiv 2510.03029](https://arxiv.org/abs/2510.03029)) and the more capable models bias toward over-building / bloated procedural logic ([AI-Generated Smells, arXiv 2605.02741](https://arxiv.org/html/2605.02741v1)). Shift-left says the cheapest smell is the one never written, and Self-Refine shows a *single* author-time critique step yields a real gain (~+13% on code — [arXiv 2303.17651](https://arxiv.org/abs/2303.17651)).
+- **Against removing the reviewer (the risk):** without *external* feedback, intrinsic self-correction often *degrades* output ([LLMs Cannot Self-Correct Reasoning Yet, ICLR 2024, arXiv 2310.01798](https://arxiv.org/abs/2310.01798)), and an LLM is **not** reliably better at *discriminating* its own output than at generating it (54/56 experiments — [SELF-[IN]CORRECT, AAAI 2025, arXiv 2404.04298](https://arxiv.org/abs/2404.04298)). The author has a structural blind spot on the code it just wrote; the independent `simplify` pass supplies the external signal (component registry + grep/LSP/graph reverse-impact, fresh eyes, different context) that the in-flight coder cannot. This also matches BALDART's own recorded principles ("no self-judging adversarial"; the refuted "Lazy Ladder pre-gen in the coder").
+
+So the fix adds **prevention in the coder** for the patterns that are pure author-time discipline (Quality + Efficiency — they need no fresh cross-codebase scan) and **keeps `simplify` untouched** as the independent net whose load-bearing value is cross-codebase **Reuse** detection. Net effect: the coder ships cleaner first drafts → the review pass finds and re-fixes less → fewer fix→re-review cycles, with the safety net intact.
+
+Design properties that make this low-risk: (1) the discipline lives in the **agent** (`coder.md`), so it reaches every spawn path — `/new`, `new2`, `/bug`, standalone — with zero per-skill wiring; (2) **no change** to the review contract — `runSimplify`, `review-cycle.md`, `new-card-review.js`, `new2.js` are all untouched, so the independent pass still runs; (3) **anti-drift via bidirectional cross-pointers** (the same pattern already used for the Reference-Aliasing rule): the full taxonomy + detection/fix workflow stay SSOT in `simplify/SKILL.md` Step 2, the coder carries a terse "keep-in-sync" mirror of the author-time subset only; (4) it does **not** duplicate what the coder already does — Reuse and Design-System are already covered by `Before Creating New Components` and STEP 8, so the new section fills exactly the Quality+Efficiency gap.
+
+**MINOR** — additive behaviour capability on the `coder` agent; no new agent/skill/command/routine/template, no new `baldart.config.yml` key (schema-change propagation rule does not apply), no install/layout change. README inventory counts unchanged.
+
+### Changed
+
+- **`framework/.claude/agents/coder.md`** — new `## Author-Time Simplicity Discipline (MUST)` section (between `Code Standards` and `Reference-Aliasing Mutation Hazards`): prevention-framed, terse one-line-per-pattern checklist mirroring the Quality + Efficiency author-time subset of `simplify/SKILL.md` Step 2, plus one Reuse reflex (no inline reimplementation of an existing utility/stdlib) and an explicit SSOT + keep-in-sync note. `Code Standards` and the closing "Keep it simple" line now point to it.
+- **`framework/.claude/skills/simplify/SKILL.md`** — Step 2 gains a back-pointer to the coder mirror, declaring this pass the independent net (load-bearing on cross-codebase Reuse) and itself the SSOT for the taxonomy (keep the coder mirror in sync).
+
 ## [4.56.3] - 2026-06-20
 
 **`/new` Codex relays made Haiku-proof — the JS now owns the success decision and deterministically recovers Codex's findings, so no relay model (whatever tier the runtime hands it) can drop them.** Direct follow-up to a user question — "why is the per-card Codex relay still running on Haiku?" Forensics on the real consumer run (reading `<session>/subagents/workflows/wf_*/agent-*.jsonl`) established two facts that recontextualise v4.56.2:

package/VERSION

@@ -1 +1 @@
-4.56.3
+4.57.0

package/framework/.claude/agents/coder.md

@@ -123,6 +123,35 @@ Before creating any new component, hook, utility, or pattern:
 - Validate inputs, handle errors gracefully.
 - Add comments only where logic is non-obvious.
 - Follow existing patterns in the codebase.
+- Apply the `## Author-Time Simplicity Discipline` below WHILE writing — do not defer it to the review pass.
+
+## Author-Time Simplicity Discipline (MUST)
+
+The `simplify` review pass (Phase 2.55 of `/new`) is the independent net that catches **cross-codebase duplication you cannot see from inside this task** — it scans the component registry + grep/LSP/graph reverse-impact with fresh eyes, in a different context. Your job is NOT to replace it but to **not author the avoidable smells in the first place**, so that pass finds and re-fixes less.
+
+Why this matters: LLM-authored code carries measurably more code smells than human reference solutions and biases toward over-building (bloated procedural logic) — the cheapest smell is the one never written. The patterns below are **author-time disciplines**: each needs no fresh codebase scan, so apply them as you type — not as a second pass on yourself (intrinsic self-review without external signal is unreliable; that is exactly what the independent `simplify` pass is for).
+
+**Quality — do NOT introduce:**
+- Redundant state (values that duplicate existing state or are derivable; effects/observers where a direct call works).
+- Parameter sprawl (new params bolted on instead of generalizing/restructuring).
+- Copy-paste with slight variation (unify into one parametrized path).
+- Leaky abstractions (don't expose internals or break existing boundaries).
+- Stringly-typed code (use the existing const/enum/string-union/branded type, not raw strings).
+- Unnecessary JSX nesting (no wrapper elements that add no layout value).
+- Unnecessary comments (WHAT / change-narration / task-ref — keep only the non-obvious WHY).
+
+**Efficiency — do NOT introduce:**
+- Unnecessary work (redundant computation, repeated reads, duplicate API calls, N+1).
+- Missed concurrency (independent operations run sequentially).
+- Hot-path bloat (blocking work added to startup / per-request / per-render paths).
+- Recurring no-op updates (add a change-detection guard so consumers aren't notified on no change).
+- Unnecessary existence checks (TOCTOU — operate directly and handle the error).
+- Memory (unbounded structures, missing cleanup, event-listener leaks).
+- Overly broad operations (read/load only the portion you need).
+
+**Reuse** is already covered by `## Before Creating New Components` above (exact/near duplication + registry check). Add one reflex: do not hand-roll logic that an existing utility OR the language/stdlib/platform already provides (**inline reimplementation**) — search before writing.
+
+SSOT + sync: this checklist is the **author-time subset**. The full taxonomy AND the detection-and-fix workflow are SSOT in `framework/.claude/skills/simplify/SKILL.md` (Step 2) — do NOT fork or expand the list here. If you extend the discipline, edit the skill and keep this mirror in sync.
 
 ## Reference-Aliasing Mutation Hazards (MUST — pre-implementation check)
 
@@ -337,7 +366,7 @@ Use judgment on review depth, but do not bypass repo-required QA gates.
 - **Don't invent skip reasons.** Phrases like `time budget`, `context budget`, `context pressure as override`, `not in scope of this card`, `optional`, or any constraint not enumerated in the card YAML or in a phase's documented Gate table are forbidden. If you genuinely cannot make progress after 3 self-heal attempts, set the card-level `status: blocked` (or `partial` if part of the card landed), leave per-requirement statuses honest, and stop. The orchestrator handles the rest.
 - **NEVER create, checkout, or switch a git branch autonomously.** See the Hard Rule at the top of this file. No `git checkout -b`, no `git switch -c`, no `git branch`, no `git worktree add`. The `git_strategy` field is descriptive context, NOT authorization. Only an explicit literal instruction in the task prompt ("create branch X", "checkout Y") authorizes branch operations. When in doubt: stay on the current branch and report back in the completion report.
 
-Keep it simple. Write good code. Ask if unsure.
+Keep it simple. Write good code. Ask if unsure. (See `## Author-Time Simplicity Discipline` — write it clean the first time.)
 
 ## Linked Skills
 

package/framework/.claude/skills/simplify/SKILL.md

@@ -42,6 +42,8 @@ If there are no git changes at all, review the most recently modified files that
 
 Use the Agent tool to launch all three agents concurrently in a single message. Pass each agent the full diff so it has the complete context.
 
+> **Author-time prevention mirror:** `coder` now applies an author-time subset of the Quality + Efficiency taxonomy below WHILE writing (`framework/.claude/agents/coder.md § Author-Time Simplicity Discipline`), so the diff this pass reviews should already be cleaner on those domains. This pass remains the **independent net** — its load-bearing value is the cross-codebase **Reuse** detection (exact/near duplicate, inline reimplementation) that the author cannot see from inside the task. This Step 2 taxonomy is the SSOT; if you change it, keep the coder mirror in sync.
+
 ### Agent 1: Duplication & Reuse Review
 
 For each new piece of code in the diff:

package/package.json

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