baldart 4.56.3 → 4.58.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.58.0] - 2026-06-20
+
+**`simplify` gains a 4th Reuse class — "a new third-party dependency reimplements a native/stdlib/platform capability" — closing the one genuine residual from the (otherwise refuted) ponytail analysis.** Follow-up to a user observation that `simplify` relates to the ponytail learnings. The accurate picture is the reverse: ponytail was **refuted, never integrated** (zero mentions anywhere in `framework/`), because `simplify` already covered its concepts in superior form. That analysis left exactly **one** genuinely uncovered item (recorded as a ~1-line residual): the reuse lens did not flag *pulling in a dependency* for something the language/stdlib/runtime/platform already does (e.g. a date/util library for what `Intl` / `Temporal` / built-ins provide). The v4.57.0 coder reflex touched only the adjacent *inline-reimplementation* (hand-rolling) case, not the new-dependency case.
+
+The residual had been tagged "measure first" under the data-driven principle, but that principle targets **arbitrary numeric thresholds** ("N lines = inline"); this is a **qualitative** reuse lens (the established you-don't-need-lodash discipline), so it ships directly. Added consistently across every parallel location: `simplify` Agent 1 (a new dependency check + the new classification), Step 3 (aggregation), Step 4 (the fix: replace with the native primitive, remove the package, or flag when removal is non-trivial/shared), the delegated workflow's Reuse lens (`new-card-review.js`), and the coder's author-time reuse reflex (now two reflexes: no inline-reimpl + no native-duplicating dependency; a genuinely needed new dep stays an ADR decision). The simplify↔coder cross-pointer's Reuse example list is updated to match.
+
+**MINOR** — additive review capability (a new finding class the `simplify` pass can surface) + the matching author-time reflex; no new agent/skill/command/routine/template, no new `baldart.config.yml` key (schema-change propagation rule does not apply), no install/layout change. The review contract (`runSimplify`, gating) is unchanged.
+
+### Changed
+
+- **`framework/.claude/skills/simplify/SKILL.md`** — Agent 1: new dependency-vs-native check (step 5) + new **"Dependency reimplements native"** reuse class; Step 3 aggregation gains it (reuse classes 1–4, then Quality/Efficiency renumbered 5/6); Step 4 gains its fix recipe; the author-time-mirror back-pointer's Reuse example list updated.
+- **`framework/.claude/workflows/new-card-review.js`** — the delegated `simplifyPrompt` Reuse lens now also covers a new third-party dependency reimplementing a native/stdlib/platform capability (parity with the skill, so the `/new` delegated path applies the lens too).
+- **`framework/.claude/agents/coder.md`** — `## Author-Time Simplicity Discipline` Reuse reflex extended from one to two reflexes: also do not add a dependency for a capability the stdlib/runtime/platform already provides (a needed new dep is an ADR decision, not a reflex).
+
+## [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.58.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 two reflexes: (1) do not hand-roll logic that an existing utility OR the language/stdlib/platform already provides (**inline reimplementation**) — search before writing; (2) do not add a third-party **dependency** for a capability the stdlib/runtime/platform already covers (e.g. `Intl`/`Temporal`/`fetch`/`structuredClone`) — a genuinely needed new dependency is an ADR decision, not a reflex.
+
+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, dependency-reimplements-native) 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:
@@ -59,12 +61,14 @@ For each new piece of code in the diff:
    reverse-impact set from the graph (and `graphify-out/GRAPH_REPORT.md` surfaces
    duplicated god-node clusters) — see `framework/agents/code-graph-protocol.md`.
 4. **Flag components that wrap the same underlying element** with minor style/prop differences.
+5. **For any newly added third-party dependency** in the diff (a new entry in the package manifest, or a first import of a package the project did not use before), check whether the language/stdlib/runtime or platform already provides the capability — prefer the native primitive over pulling in a dependency for it (e.g. `Intl`/`Temporal`/`Array`/`fetch`/`structuredClone` vs a util or date library).
 
 Classify each finding as:
 
 - **Exact duplicate** — same logic exists elsewhere. Use the existing one. Delete the new one.
 - **Near duplicate** — similar logic with minor differences. Extract a shared version with parameters.
 - **Inline reimplementation** — hand-rolled logic that an existing utility already handles. Replace with the utility call.
+- **Dependency reimplements native** — a newly added third-party dependency duplicates a capability the language/stdlib/runtime or platform already provides. Prefer the native primitive; flag the dependency as removable. (A genuinely needed new dependency is separately an ADR trigger, not a simplify removal.)
 
 ### Agent 2: Code Quality Review
 
@@ -116,8 +120,9 @@ Collect results from all three agents. For each finding, categorize as:
 1. **Exact duplicate** — same logic exists elsewhere. Use the existing one. Delete the new one.
 2. **Near duplicate** — similar logic with minor differences. Extract a shared version with parameters.
 3. **Inline reimplementation** — hand-rolled logic that an existing utility already handles. Replace with the utility call.
-4. **Quality issue** — hacky pattern from Agent 2. Fix directly.
-5. **Efficiency issue** — performance problem from Agent 3. Fix directly.
+4. **Dependency reimplements native** — a new third-party dependency duplicates a stdlib/platform capability. Replace with the native primitive; remove the dependency.
+5. **Quality issue** — hacky pattern from Agent 2. Fix directly.
+6. **Efficiency issue** — performance problem from Agent 3. Fix directly.
 
 If no issues are found, say so and stop. Do not invent problems.
 
@@ -128,6 +133,7 @@ For each finding, apply the fix directly:
 - **Exact duplicates**: Delete the new code, import the existing version, update all references.
 - **Near duplicates**: Extract a shared function/component/hook to the project's shared directory resolved from `baldart.config.yml` (see "When extracting shared code" below). Update all call sites to use the shared version.
 - **Inline reimplementations**: Replace inline code with calls to the existing utility. Add imports.
+- **Dependency reimplements native**: Replace the dependency's usages with the native primitive, remove the package from the manifest, and update imports. If the removal is non-trivial or the dependency is shared by other code, flag it instead of forcing the removal in this pass.
 - **Quality issues**: Apply the fix inline (remove redundant state, simplify JSX nesting, replace string literals with constants, etc.).
 - **Efficiency issues**: Apply the fix inline (parallelize independent calls, add change-detection guards, batch reads, etc.).
 

package/framework/.claude/workflows/new-card-review.js

@@ -304,7 +304,7 @@ const qaPrompt =
 
 function simplifyPrompt(c) {
   return `Simplify analysis (read-only — you do NOT edit, the workflow applies fixes afterward) over ONE card's committed diff, per ${protocolRef} (Phase 2.55). Cover all THREE lenses and return findings:\n` +
-    `  • Reuse — newly written code that duplicates an existing util/helper; inline logic that could use existing code.\n` +
+    `  • Reuse — newly written code that duplicates an existing util/helper; inline logic that could use existing code; a NEW third-party dependency that reimplements a capability the language/stdlib/runtime/platform already provides (prefer the native primitive).\n` +
     `  • Quality — redundant state, parameter sprawl, copy-paste with slight variation, leaky abstractions, stringly-typed code where enums exist, unnecessary JSX nesting, WHAT-comments / narration.\n` +
     `  • Efficiency — redundant computation, duplicate API calls, N+1, missed concurrency, hot-path bloat, missing change-detection guards, unbounded structures.\n\n` +
     `${cardScopeBrief(c)}\n\n${baselineBrief}\n\n` +

package/package.json

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