baldart 4.89.0 → 4.89.1

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.89.1] - 2026-07-01
+
+**`/new` tracker-write economy — remove the phase-entry write prompts.** An audit (mayo FEAT-0064) measured **20 orchestrator turns whose only tool call was a tracker `Edit`** (~5-11M tokens of pure `cache_read` replay, ~3-6% of the run). The § "Context economy" rule already forbids lone tracker-`Edit` turns (and the metric is trending down: 38 → 28 → 20), so this is a compliance gap, not a missing rule. The non-redundant fix: the per-phase reference modules carried ~9 numbered `**Update tracker**: phase = "X"` **phase-entry** steps (no data) that actively prompt a standalone write, contradicting the global co-emit rule. Removing that prompt at the source is more effective than more prose.
+
+**PATCH** — context-economy refinement, no functional behavior change. `/new`-only (`new2` writes its tracker via the JS `ledger()` helper, which costs no orchestrator turn — no parallel change). **No new `baldart.config.yml` key**.
+
+### Changed
+
+- **Phase-entry markers removed** across `implement.md` / `review-cycle.md` / `completeness.md` / `commit.md`: the standalone `phase = "1-claim|2-implement|2.55-simplify|2.6-e2e-review|3-doc-review|3.5-qa|2.5-completeness|2.5b-ac-closure|4-commit"` steps are reworded to "**Enter phase X — no standalone tracker write**" pointing at the allowlist. The card-claim (moves the card to `## Current Card`) and the Phase-4 entry-assertion are preserved but explicitly co-emitted. Step numbers are unchanged (no renumbering / no broken cross-refs).
+- **Data-carrying DONE-markers kept** (findings / retry counts / `qa_first_attempt` / AC-closure ledger — Phase-8 telemetry producers), now governed by the allowlist to co-emit with the phase's last tool call.
+- **`SKILL.md` § Context Tracking** gains an explicit **tracker-write allowlist**: the ONLY writes are `phase_module_loaded`, a data-carrying DONE-marker, a commit record, a gate verdict, and a blocker/flag — all co-emitted; there is NO "entering phase X" write. Recovery is unchanged (§ "Context recovery protocol" reconstructs the phase from commit + `phase_module_loaded` + backlog).
+
 ## [4.89.0] - 2026-07-01
 
 **Mockup-first build routing — a card with a mockup ALWAYS builds via `/ui-implement` → `ui-expert`.** A `/new` post-mortem (mayo FEAT-0064) found two UI cards with a `links.design_src` mockup built by `coder` instead of `ui-expert`, causing layout drift (caught by the v4.78.0 fidelity gate) + three avoidable rework passes + a full `balanced` review (~174M tokens). Root cause: the v4.82.0 `/ui-implement` delegation gate was positioned **inside** `implement.md` step 7's briefing, structurally **subordinate** to the `owner_agent` router (step 6b) — so a card whose `owner_agent` is `coder` (which `prd-card-writer` Rule B correctly assigns to a **mixed UI+logic** card, since `ui-expert` has UI-only scope) resolved `spawn=coder` and the delegation note never fired. `new2.js` was worse: it dispatched `owner_agent` with no delegation gate at all.

package/VERSION

@@ -1 +1 @@
-4.89.0
+4.89.1

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

@@ -171,6 +171,7 @@ Trunk branch: [resolved git.trunk_branch — Phase 0 step 0 populates]
 
 - **Before starting a card**: move it to `## Current Card` with phase info, and record `phase_module_loaded: <modulo>` as you Read each phase module (per § "Routing" HARD RULE) so context recovery can re-load it.
 - **At card-state-changing boundaries only** (NOT after every sub-step): update the tracker's phase status when something recovery-relevant changes — a commit, a gate verdict, a blocker, a phase-module load. **Always co-emit the `Edit` with that action's tool call** (never a standalone status-only turn — § "Context economy" makes a lone tracker-`Edit` turn a violation). A measured run still paid 38 standalone tracker-Edit turns (~13.6M / ~9%) because "after each phase" was read as "emit a status turn per phase" — so the cadence is deliberately coarsened here: between two real actions there is nothing to write. Fine-grained phase recovery does not depend on per-phase writes — § "Context recovery protocol" reconstructs the current phase from the last commit + `phase_module_loaded` + backlog statuses.
+  > **Tracker-write ALLOWLIST (the ONLY events that write the tracker — all co-emitted with their tool call, never a turn of their own):** (a) **`phase_module_loaded`** — folded into the `Read` of the module; (b) a **phase DONE-marker that carries data** (findings / verdict / retry count / `qa_first_attempt` / AC-closure ledger) — folded into the phase's last real tool call; (c) a **commit record** — folded into the commit `Bash`; (d) a **gate verdict** (e2e / codex) — folded into its resolution; (e) a **blocker / flag**. **There is NO "entering phase X" write** — a bare `phase = "<name>"` line with no data and no accompanying action is NOT a tracker trigger (the phase-entry markers were removed from the per-phase modules for exactly this reason). If you are about to `Edit` the tracker with only a phase name, **do not** — the DONE-marker + `phase_module_loaded` + commit already carry recovery.
 - **After completing a card**: move it from `Current Card` to `## Completed Cards` with:
   - Commit hash
   - One-line summary of what was implemented

package/framework/.claude/skills/new/references/commit.md

@@ -6,7 +6,7 @@
 
 > Sequential-mode global step numbering resumes here at 26 (Phase 3.5 ended at 25; Phase 3.7 used its own local C.0–C.6 counter). The tracker phase-string `4-commit` therefore maps to step 26, NOT a second step 25.
 
-26. **Update tracker**: phase = "4-commit". **Entry assertion** — before committing, verify the Phase 3.7 e2e re-run obligation was honored: read the tracker for `e2e-rerun: triggered` / `e2e-rerun: not-needed`. If Phase 3.7 touched UI files but no `e2e-rerun` entry exists, do NOT commit yet — go run the re-run per Phase 3.7 step 6 first. Also confirm Phase 3.5/3.7 fixes did not leave lint/tsc broken: if the Phase 3.7 fix sub-loop applied any patch, run `npm run lint` + `npx tsc --noEmit` (when typescript) once before committing — when `has_toolchain`, the configured `toolchain.commands.{lint,typecheck}` verbatim (§ "Toolchain gates") — (redirect to disk per § "Context economy").
+26. **Phase 4 entry assertion** (no standalone `phase = "4-commit"` status turn — § "Context Tracking" allowlist; the tracker write for this phase is the commit record at step 29, co-emitted with the commit). **Verify before committing** that the Phase 3.7 e2e re-run obligation was honored: read the tracker for `e2e-rerun: triggered` / `e2e-rerun: not-needed`. If Phase 3.7 touched UI files but no `e2e-rerun` entry exists, do NOT commit yet — go run the re-run per Phase 3.7 step 6 first. Also confirm Phase 3.5/3.7 fixes did not leave lint/tsc broken: if the Phase 3.7 fix sub-loop applied any patch, run `npm run lint` + `npx tsc --noEmit` (when typescript) once before committing — when `has_toolchain`, the configured `toolchain.commands.{lint,typecheck}` verbatim (§ "Toolchain gates") — (redirect to disk per § "Context economy").
 27. Stage and commit **all changes together** in the worktree using format `[CARD-ID] Brief description` (MUST per AGENTS.md). Include all relevant files — implementation, review fixes, QA-driven fixes, and doc updates in a single commit. Do NOT merge or push yet — that happens post-batch.
     - **IMPORTANT — explicit staging**: NEVER use `git add -A` or `git add .`. Always stage files by explicit name:
       ```bash

package/framework/.claude/skills/new/references/completeness.md

@@ -34,7 +34,7 @@ Before triggering any review, you MUST verify that the coder agent implemented *
    Also check: if the card has conditional requirements but the completion report has no
    `conditional_items` section → flag as `Missing` (the coder must document the branch taken).
 
-1. **Update tracker**: phase = "2.5-completeness".
+1. **Enter Phase 2.5 (completeness)** — **no standalone tracker write** for phase entry (§ "Context Tracking" allowlist; the tracker records only `2.5-completeness DONE` at step 6, co-emitted). Proceed directly to the next step.
 2. Re-read the backlog card (`requirements`, `acceptance_criteria`, `unknowns`, and `definition_of_done` fields).
 3. Build a checklist — one row per item:
 
@@ -227,7 +227,7 @@ This gate enforces `framework/agents/workflows.md § Scope Closure Discipline` a
 
 **Step-by-step**:
 
-1. **Update tracker**: phase = "2.5b-ac-closure".
+1. **Enter Phase 2.5b (AC-closure)** — **no standalone tracker write** for phase entry (§ "Context Tracking" allowlist; the tracker records only `2.5b-ac-closure DONE` + the AC Closure Ledger at step 6, co-emitted). Proceed directly to the next step.
 
 2. **Build the AC Closure Ledger** — one row per `acceptance_criteria` entry from the card YAML (NOT requirements — only the AC list, because ACs are the user-facing contract):
 

package/framework/.claude/skills/new/references/implement.md

@@ -3,7 +3,7 @@
 > **Modulo `/new`** — eseguilo, poi torna al core § "Routing" per la fase successiva. I `§ "..."` (Context economy, Context Tracking, Trivial-card fast-lane, Risk-signal detector, Fix Application Log) vivono nel **core SKILL.md**.
 
 ### Phase 1 — Claim & Context
-1. **Update tracker**: set current card, phase = "1-claim".
+1. **Claim the card** — move it to `## Current Card` in the tracker. **Co-emit this `Edit` with the first real tool call of this phase** (the codebase-architect spawn / the card-YAML `Read`), never as a standalone turn (§ "Context Tracking" allowlist). Do NOT spend a turn on a bare `phase = "1-claim"` status write.
 2. **`depends_on` gate (BEFORE claiming)** — read the card's `depends_on` field. For each listed card ID:
    - Read that card's backlog YAML and check its `status` field.
    - If NOT `DONE` → HALT: log in `## Issues & Flags` and ask the user: "Card <CARD-ID> depends on <DEP-ID> which is `<status>`. Proceed anyway, or wait?" Do not start implementation until the user responds explicitly. **The card status is NOT written until this gate passes** — so a HALT leaves the card untouched (no stale `IN_PROGRESS` for the next run to mis-read). **When AUTONOMOUS (SKILL.md § "AUTONOMOUS RESOLUTION RULE"): do NOT HALT — DAG-exclude this card from the runnable set (defer it) and materialize ONE follow-up card (no-drop); NEVER proceed-anyway, NEVER mark DONE.**
@@ -48,7 +48,7 @@
 5b. **Persist the architecture baseline for reuse (since v3.35.0)** — write the **untruncated codebase-architect task result verbatim** (the full Task-tool output: file paths, type signatures, patterns, high-risk paths) to `/tmp/arch-baseline-<CARD-ID>.md`. This is NOT the 1-2-line tracker summary from step 5 — serialize the agent's complete output to disk BEFORE you summarize it for the tracker, so Phase 3.7's per-card `/codexreview` (lean mode, reuses this file instead of re-spawning `codebase-architect`) gets enough detail to ground a reviewer. If you summarize first and write the summary, the lean contract is defeated.
 
 ### Phase 2 — Implement (self-healing, up to 3 retries)
-6. **Update tracker**: phase = "2-implement".
+6. **Enter Phase 2 (implement)** — **no standalone tracker write** for phase entry (§ "Context Tracking" allowlist: the phase is recovered from the last commit + `phase_module_loaded` + backlog; the tracker records only `2-implement DONE` at step 11, co-emitted). Proceed directly to 6a.
 6a. **Mockup-build delegation gate (PRIMARY — precedes the owner_agent router).** The BUILD agent for a card with a mockup is decided by the **mockup**, NOT by `owner_agent`. This gate is structurally FIRST so a stale/mixed-card `owner_agent: coder` can never send a UI build to `coder` (the FEAT-0064 failure: a card with `links.design_src` built by coder because the delegation note was buried downstream in the step-7 briefing). SSOT: `framework/agents/design-system-protocol.md` § "Route-Independent Fidelity & Coverage Obligation".
 
    ```

package/framework/.claude/skills/new/references/review-cycle.md

@@ -124,7 +124,7 @@ After completeness is verified, clean up the implementation before it reaches re
 
 **Step-by-step**:
 
-1. **Update tracker**: phase = "2.55-simplify".
+1. **Enter Phase 2.55 (simplify)** — **no standalone tracker write** for phase entry (§ "Context Tracking" allowlist; the tracker records only `2.55-simplify DONE` at step 6, co-emitted). Proceed directly to step 2.
 2. Capture the current card's changes to disk — `git diff > /tmp/diff-<CARD-ID>.txt` in the worktree (**redirect, not inline** — per § "Context economy" → Diffs to disk).
 3. Launch **three agents in parallel** (single message). Each receives the **path** `/tmp/diff-<CARD-ID>.txt` and Reads the diff itself — do NOT paste the full diff into the prompts:
 
@@ -200,7 +200,7 @@ auto-skips on backend-only cards, and BLOCKS the commit on gating findings.
 When the gate above passes, the orchestrator invokes `/e2e-review` in
 **programmatic mode**:
 
-1. **Update tracker**: phase = "2.6-e2e-review".
+1. **Enter Phase 2.6 (e2e-review)** — **no standalone tracker write** for phase entry (§ "Context Tracking" allowlist; the tracker records only the e2e gate verdict, co-emitted with its resolution). Proceed directly to step 2.
 2. Spawn the skill with the payload:
 
    ```json
@@ -284,7 +284,7 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
 
 > **Deferral gate (since v4.7.0 — enumerated, `review_profile`-driven)**: SKIP per-card doc-review and defer it to the **Final Review F.3 doc-reviewer** (which runs over the entire batch) when the card is **`review_profile == light` AND its committed diff touches NO documentation file** (no `.md`, no path under `${paths.references_dir}`, no data-model/ssot/api doc). These are small code changes with no doc surface of their own; their only doc concern is drift, which the batch-wide Final doc-reviewer catches. Log `doc-review: DEFERRED to Final FULL gate (light, no doc files in diff)` and proceed to Phase 3.5. **KEEP per-card doc-review** for: `balanced`/`deep` cards, ANY card whose diff touches a doc file (the change IS doc-relevant), and trivial cards (doc-review is their primary gate — § "Trivial-card fast-lane", unchanged). Never defer "for time" — the only enumerated reason is `light + non-doc diff`.
 
-12. **Update tracker**: phase = "3-doc-review".
+12. **Enter Phase 3 (doc-review)** — **no standalone tracker write** for phase entry (§ "Context Tracking" allowlist; the tracker records only `3-doc-review DONE` at step 17, co-emitted). Proceed directly to the next step.
 13. Build a **Doc Sync Context** block. The coder committed in Phase 2, so detect the card's changed files against the trunk (a bare `HEAD` diff would be empty post-commit):
     ```bash
     git diff --name-only "$TRUNK...HEAD" 2>/dev/null || git diff --name-only HEAD~1..HEAD
@@ -346,7 +346,7 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
 
 ### Phase 3.5 — QA Validation
 
-18. **Update tracker**: phase = "3.5-qa".
+18. **Enter Phase 3.5 (QA)** — **no standalone tracker write** for phase entry (§ "Context Tracking" allowlist; the tracker records only `3.5-qa DONE` at step 25, co-emitted, incl. the `qa_first_attempt` producer). Proceed directly to step 19.
 19. **Select QA profile**: READ the card's `review_profile` field (use verbatim); only compute via the QA Profile Selector above (whose criteria SSOT is `prd-card-writer.md § Rule C`) when the field is absent (legacy card). Log the chosen profile and its source (`from card` | `computed`) in the tracker (1 line).
 20. **If profile is SKIP**: log "QA skipped — [reason]" in the tracker. Proceed to Phase 4.
 21. **If profile is LIGHT**: SKIP qa-sentinel. Phase 2 step 8 ran lint/tsc/test/build, AND the two code-mutating phases that follow it (Phase 2.55 Simplify, Phase 3 doc-reviewer) each re-run lint + tsc on their post-mutation output (so the static checks cover the committed code, not just the pre-mutation code). Log "QA LIGHT skipped — lint/tsc/test/build passed in Phase 2 and lint/tsc re-ran post-mutation in 2.55/3" in the tracker. Proceed to Phase 4.

package/package.json

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