baldart 3.28.1 → 3.28.2

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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).
 
+## [3.28.2] - 2026-05-28
+
+Telemetry-only release. Adds structured logging for fix-application decisions in `/new` Phases 2.55 / 3 / 3.5 / 3.7. **Zero behavior change** — the orchestrator's decisions remain identical to v3.28.1. The goal is to measure, with real data, whether the per-phase delegation rules need to change in a future release.
+
+### Added — `## Fix Application Log` section in tracker
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)**: new section **"Fix Application Log Schema (telemetry)"** inserted before Phase 2.55. Defines a pipe-separated row format (`<phase> | <domain> | est_lines=<n> | decision=<...> | applied_by=<...> | <key=val>...`) appended to the tracker's `## Fix Application Log` section. Phases 2.55 / 3 / 3.5 / 3.7 each instructed to log one row per finding processed (including skipped). Cost: ~1-2 KB per card, negligible context impact.
+- Per-phase logging instructions added to Phase 2.55 step 4 (simplify reuse/quality/efficiency), Phase 3 step 15 (doc), Phase 3.5 step 23 (qa-sentinel blockers), Phase 3.7 step 4 (codex BLOCKER/HIGH + false-positive-filtered). Each phase classifies finding `domain` consistently with the schema enum.
+
+### Added — Aggregator script
+
+- **[framework/scripts/analyze-fix-application.js](framework/scripts/analyze-fix-application.js)**: zero-dependency Node script. Reads N tracker files (shell-expanded glob), parses rows in the `## Fix Application Log` section, aggregates by `phase × domain × decision × applied_by`, outputs a tabular summary plus an automatic violation footer flagging inline-apply on doc / security / migration domains. Usage: `node framework/scripts/analyze-fix-application.js docs/references/trackers/*.md`.
+
+### Added — Telemetry reading guide
+
+- **[framework/docs/FIX-APPLICATION-TELEMETRY.md](framework/docs/FIX-APPLICATION-TELEMETRY.md)**: new doc. Explains why telemetry exists, the row schema (cross-references SKILL.md as SSOT), how to read the analyzer output, violation patterns vs delegation candidates vs healthy patterns, and the trigger conditions for the future Release C decision (threshold rule vs Phase 2.55→3 merge).
+
+### Rationale
+
+This release is the first of a 3-release sequence (A: telemetry → B: loophole + 2 known violations → C: conditional threshold rule). The decision to instrument *before* changing rules avoids inventing arbitrary thresholds without data — see plan file at `/Users/antoniobaldassarre/.claude/plans/sto-notando-una-cosa-misty-lightning.md` for full reasoning. Schema-change propagation rule: **no new `baldart.config.yml` keys** in this release.
+
 ## [3.28.1] - 2026-05-28
 
 Patch su tre drift segnalati dal curator dopo v3.28.0 install in `mayo`:

package/VERSION

@@ -1 +1 @@
-3.28.1
+3.28.2

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

@@ -938,6 +938,29 @@ If at any point in Phases 2 / 2.5 / 2.5b you detect context-window pressure (you
 
 Auto Mode does NOT override this rule. "Bias toward proceeding" applies to routine decisions ("should I rerun this check?", "should I confirm this safe rename?"), NEVER to scope reduction.
 
+### Fix Application Log Schema (telemetry)
+
+Every fix-application decision in Phases 2.55 / 3 / 3.5 / 3.7 appends one row to the tracker's `## Fix Application Log` section. Telemetry only — does NOT alter behaviour. The aggregated log feeds `framework/scripts/analyze-fix-application.js`, which surfaces which fixes the orchestrator applied inline vs delegated to coder, per-phase distribution of `est_lines`, and violation patterns (doc/security findings applied inline). Full reading guide: `framework/docs/FIX-APPLICATION-TELEMETRY.md`.
+
+**Row format** (one row per finding processed, including skipped):
+
+```
+<phase> | <domain> | est_lines=<n> | decision=<inline|coder|coder-batch|skipped> | applied_by=<orchestrator|coder|orchestrator-fallback|-> | <key=val>...
+```
+
+| Field | Values |
+|---|---|
+| `phase` | `2.55`, `3`, `3.5`, `3.7` |
+| `domain` | `simplify-reuse`, `simplify-quality`, `simplify-efficiency`, `doc`, `qa-blocker`, `qa-major`, `qa-minor`, `qa-none`, `codex-security`, `codex-correctness`, `codex-other` |
+| `est_lines` | Orchestrator's at-a-glance estimate of the diff size suggested by the finding. Bucketed `1-5` / `6-20` / `21+` is sufficient — exact precision not required. Use `0` if no patch (e.g. skipped). |
+| `decision` | `inline` (orchestrator applied), `coder` (single coder spawn for this finding), `coder-batch` (folded into a batched coder spawn covering ≥2 findings), `skipped` (false positive / not worth addressing / no findings) |
+| `applied_by` | `orchestrator`, `coder`, `orchestrator-fallback` (agent crash with non-domain-override fallback — see Sub-agent failure protocol), `-` (skipped) |
+| Trailing `key=val` | Phase-specific extras: `finding=<1-line summary>`, `severity=<BLOCKER\|HIGH\|MEDIUM\|FALSE-POSITIVE>`, `retry=<n>`, `reason=<...>` |
+
+**Write target**: the same tracker file the orchestrator already writes per-card status to (path resolved from `${paths.references_dir}/trackers/` or the project's tracker convention). Section header `## Fix Application Log` is created on first row of the card. Append-only — never rewrite previous rows.
+
+**Cost**: ~80-120 bytes per row, ~5-15 rows per card. Negligible context impact, large analytical value.
+
 ### Phase 2.55 — Simplify (code cleanup before review)
 
 After completeness is verified, clean up the implementation before it reaches reviewers and E2E tests. This phase launches three parallel agents on the card's diff, then applies fixes directly.
@@ -954,7 +977,9 @@ After completeness is verified, clean up the implementation before it reaches re
 
 4. Aggregate findings from all three agents. For each finding:
    - **Valid** → fix directly (no coder agent spawn — apply edits inline).
-   - **False positive / not worth addressing** → skip silently, do not log.
+   - **False positive / not worth addressing** → skip silently, do not surface in user output.
+
+   **Telemetry (Fix Application Log)** — for EVERY finding (valid OR skipped) append one row to the tracker's `## Fix Application Log` section per the schema above. Use `domain=simplify-{reuse|quality|efficiency}` matching the originating agent. Valid: `decision=inline | applied_by=orchestrator | est_lines=<n> | finding=<1-line>`. Skipped: `decision=skipped | applied_by=- | est_lines=0 | reason=<false-positive|not-worth-addressing>`.
 
 5. After all fixes, run `npm run lint` and `npx tsc --noEmit` to confirm nothing broke.
    If either fails, fix the regression (up to 2 retries).
@@ -1114,6 +1139,8 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
     Doc-reviewer collects findings WITHOUT making changes.
 14. **Obsidian Corpus Dispatch**: Parse section H from doc-reviewer findings. If `Trigger: YES`, dispatch the `obsidian-sync` agent (`.claude/agents/obsidian-sync.md`) with the listed paths after all fixes are applied (step 16). If `Trigger: NO`, skip. This is non-blocking -- do not wait for obsidian-sync to complete before proceeding.
 15. If doc findings exist, invoke the **coder** agent once to apply **ALL doc fixes in one pass**.
+
+    **Telemetry** — after the coder returns, append one row per doc finding to `## Fix Application Log`: `3 | doc | est_lines=<n> | decision=coder-batch | applied_by=coder | finding=<1-line>`. If 0 findings, append one row: `3 | doc | est_lines=0 | decision=skipped | applied_by=- | reason=no-findings`.
 16. Run `npm run lint` and `npx tsc --noEmit` to verify nothing broke. If any check fails, apply the self-healing retry loop (up to 3 times, no user prompt).
 17. **Update tracker**: phase = "3-doc-review DONE", log doc findings count, fixes applied.
     If doc-reviewer found a recurring gap, append 1-line to `## Lessons Learned`:
@@ -1154,6 +1181,7 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
     - After coder fixes, re-invoke `qa-sentinel` in the same mode to re-validate. Repeat up to **2 times**.
     - If still FAIL after 2 retries: log in `## Issues & Flags` and **ask the user** whether to proceed or stop.
     - The commit in Phase 4 MUST NOT happen until QA verdict is PASS (or user explicitly overrides).
+    - **Telemetry** — after each coder spawn, append one row per blocker to `## Fix Application Log`: `3.5 | qa-blocker | est_lines=<n> | decision=coder | applied_by=coder | retry=<0|1|2>`. After PASS without any spawn (initial verdict PASS), append one row: `3.5 | qa-none | est_lines=0 | decision=skipped | applied_by=- | reason=qa-pass`.
 24. **Update tracker**: phase = "3.5-qa DONE", log: profile used, verdict (PASS/FAIL/SKIP), confidence %, findings count (blockers/majors/minors), findings file path.
 
 ### Phase 3.7 — Pre-Merge Codex Review Gate (MANDATORY — UNCONDITIONAL)
@@ -1248,6 +1276,7 @@ For EVERY card (no conditional skip):
    - If 0 BLOCKER and 0 HIGH → log `verdict: PASS — proceeding to Phase 4` in tracker. Done.
    - If 1+ BLOCKER OR 1+ HIGH → spawn `coder` agent with the report path + list of VERIFIED bugs to fix. After coder fixes, re-invoke `/codexreview <CARD-ID>` to re-validate. Repeat **max 2 times**.
    - If still BLOCKER/HIGH after 2 retries → log in `## Issues & Flags` and **ask the user** whether to proceed, escalate, or stop. The Phase 4 commit MUST NOT happen until High-Risk Gate verdict is PASS or user explicitly overrides.
+   - **Telemetry** — for EVERY codex finding processed (verified BLOCKER, verified HIGH, or false-positive-filtered), append one row to `## Fix Application Log`: `3.7 | codex-<security|correctness|other> | est_lines=<n> | decision=<coder|skipped> | applied_by=<coder|-> | severity=<BLOCKER|HIGH|FALSE-POSITIVE> | retry=<n>`. Classify domain: `security` for findings touching RLS / auth / permissions / payments; `correctness` for logic / data integrity / race conditions; `other` for everything else.
 
 5. **Update tracker**: phase = `3.7-highrisk DONE`, log final verdict, retry count, list of fixed findings, and the report path.
 

package/framework/docs/FIX-APPLICATION-TELEMETRY.md

@@ -0,0 +1,80 @@
+# Fix Application Telemetry
+
+This doc describes the telemetry layer added to `/new` (Phases 2.55 / 3 / 3.5 / 3.7) that records, for every check finding, who applied the fix (orchestrator inline vs `coder` subagent) and how big the diff was. The layer is **observation only** — it does not change `/new`'s behaviour. It exists so we can decide, with real data, whether the per-phase delegation rules need to change.
+
+## Why this exists
+
+Empirical observation showed that fixes flagged by the simplify / doc-reviewer / qa-sentinel / codex agents often get applied **directly by the orchestrator** instead of being delegated to the `coder` agent. The cost is twofold: (1) the orchestrator does not inherit the coder's system prompt + project overlay (testing conventions, naming, project rules), and (2) inlining 5+ agent outputs saturates the orchestrator's context window mid-card.
+
+Before changing the rules — which would mean inventing thresholds, domain overrides, and escape valves — we measure the current state. The schema below is the contract.
+
+## Schema (SSOT)
+
+Authoritative definition lives in `framework/.claude/skills/new/SKILL.md` → section **"Fix Application Log Schema (telemetry)"**. The row format:
+
+```
+<phase> | <domain> | est_lines=<n> | decision=<inline|coder|coder-batch|skipped> | applied_by=<orchestrator|coder|orchestrator-fallback|-> | <key=val>...
+```
+
+Each row is appended to the tracker's `## Fix Application Log` section. One row per finding, including findings the orchestrator skipped as false-positive. The trailing `key=val` pairs are phase-specific extras (`finding=<1-line>`, `severity=<...>`, `retry=<n>`, `reason=<...>`).
+
+## How to read the data
+
+Run the aggregator:
+
+```bash
+node framework/scripts/analyze-fix-application.js docs/references/trackers/*.md
+```
+
+(Substitute the actual tracker directory if your project uses a different `${paths.references_dir}`.)
+
+Output is a tabular summary grouped by `phase × domain × decision × applied_by`, plus a violation-pattern footer.
+
+### Patterns to look for
+
+**Violation patterns** — these should be zero. If they're non-zero, the orchestrator is bypassing a delegation rule:
+
+| Pattern | What it means |
+|---|---|
+| `3 \| doc \| ... \| applied_by=orchestrator` | Phase 3 doc-review fix applied inline (violates `SKILL.md:1116` "invoke the coder agent once"). |
+| `3.7 \| codex-security \| ... \| applied_by=orchestrator` | Codex HIGH security finding fixed inline (violates `SKILL.md:1249` "spawn `coder` agent"). |
+| `* \| * \| ... \| applied_by=orchestrator-fallback` | Sub-agent failed and orchestrator fell back to inline. Expected to be rare; investigate if frequent. |
+
+The analyzer script flags these in its footer automatically.
+
+**Delegation candidates** — patterns suggesting the rule could be tightened:
+
+| Pattern | What it suggests |
+|---|---|
+| `2.55 \| simplify-* \| est_lines≥6 \| decision=inline \| applied_by=orchestrator` (high count) | Large simplify refactors applied inline. Candidate for threshold-based delegation. |
+| `2.55 \| simplify-* \| ... \| applied_by=orchestrator` total lines > 50/card avg | Cumulative inline diff bloating orchestrator context. Candidate for `coder-batch`. |
+| `3.5 \| qa-blocker \| retry=2` (many rows) | Coder not converging on QA fixes in 2 retries. Candidate for revised qa-sentinel feedback loop. |
+
+**Healthy patterns**:
+
+| Pattern | What it means |
+|---|---|
+| `2.55 \| simplify-* \| est_lines∈[1-5] \| decision=inline \| applied_by=orchestrator` | Small inline fixes — efficient, low cost. Expected majority of Phase 2.55. |
+| `3 \| doc \| ... \| decision=coder-batch \| applied_by=coder` | Doc fixes batched into one coder spawn. Expected for every card with doc impact. |
+| `3.7 \| * \| decision=skipped \| applied_by=- \| severity=FALSE-POSITIVE` | Codex false positives correctly filtered. |
+
+## When to act on the data
+
+After roughly **10 cards** of telemetry, run the analyzer and look at:
+
+1. **Violation count**. If non-zero, the rules are being bypassed — Release B (loophole fix + Phase 3 reinforcement) should already have made these zero.
+2. **Phase 2.55 inline distribution**. If `est_lines≥6 | applied_by=orchestrator` exceeds 30% of Phase 2.55 rows, Release C (threshold rule) becomes worth considering.
+3. **Mean inline diff per card**. Compute `(sum of est_lines for orchestrator rows) / (number of cards)`. > 50 indicates context bloat.
+
+The full decision tree for Release C lives in the plan file (`/Users/antoniobaldassarre/.claude/plans/sto-notando-una-cosa-misty-lightning.md` → "Release C — Threshold Rule (CONDIZIONALE)").
+
+## Cost
+
+Per-card overhead: 5-15 rows × ~80-120 bytes = ~1-2 KB added to the tracker. Orchestrator context impact: negligible (tracker is appended to disk, not held in context after each phase). Analysis cost: a single Node script invocation. The aggregator has zero dependencies and runs in well under a second on hundreds of trackers.
+
+## Pointers
+
+- Schema definition (canonical): `framework/.claude/skills/new/SKILL.md` → "Fix Application Log Schema (telemetry)"
+- Per-phase logging instructions: SKILL.md Phase 2.55 step 4, Phase 3 step 15, Phase 3.5 step 23, Phase 3.7 step 4
+- Aggregator script: `framework/scripts/analyze-fix-application.js`
+- Decision plan: `/Users/antoniobaldassarre/.claude/plans/sto-notando-una-cosa-misty-lightning.md`

package/framework/scripts/analyze-fix-application.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// Read N tracker files passed as args (shell-expanded glob), extract rows from
+// each file's "## Fix Application Log" section, aggregate by
+// phase × domain × decision × applied_by, print a summary table.
+//
+// Usage:
+//   node framework/scripts/analyze-fix-application.js docs/references/trackers/*.md
+//   node framework/scripts/analyze-fix-application.js path/to/tracker1.md path/to/tracker2.md
+//
+// Schema (must match framework/.claude/skills/new/SKILL.md "Fix Application Log Schema"):
+//   <phase> | <domain> | est_lines=<n> | decision=<...> | applied_by=<...> | <key=val>...
+
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const args = process.argv.slice(2).filter((a) => !a.startsWith('-'));
+if (args.length === 0) {
+  console.error('Usage: analyze-fix-application.js <tracker-file>...');
+  console.error('Pass shell-expanded glob, e.g. docs/references/trackers/*.md');
+  process.exit(2);
+}
+
+const SECTION_RE = /^##\s+Fix Application Log\s*$/i;
+const ROW_RE = /^([\w.]+)\s*\|\s*([\w-]+)\s*\|\s*est_lines=(\d+)\s*\|\s*decision=([\w-]+)\s*\|\s*applied_by=([\w-]+)(?:\s*\|\s*(.*))?$/;
+
+const buckets = new Map(); // key = "phase|domain|decision|applied_by" → { count, est_sum, est_n }
+let totalRows = 0;
+let filesParsed = 0;
+let filesSkippedNoSection = 0;
+
+for (const arg of args) {
+  let content;
+  try {
+    content = fs.readFileSync(arg, 'utf8');
+  } catch (err) {
+    console.error(`skip ${arg}: ${err.message}`);
+    continue;
+  }
+  filesParsed += 1;
+
+  const lines = content.split(/\r?\n/);
+  let inSection = false;
+  let sawSection = false;
+  for (const line of lines) {
+    if (SECTION_RE.test(line)) {
+      inSection = true;
+      sawSection = true;
+      continue;
+    }
+    if (inSection && /^##\s+\S/.test(line)) {
+      // next H2 section starts — stop
+      inSection = false;
+      continue;
+    }
+    if (!inSection) continue;
+    const m = line.match(ROW_RE);
+    if (!m) continue;
+    const [, phase, domain, estLinesStr, decision, appliedBy] = m;
+    const key = `${phase}|${domain}|${decision}|${appliedBy}`;
+    const est = parseInt(estLinesStr, 10);
+    const bucket = buckets.get(key) || { count: 0, estSum: 0, estN: 0 };
+    bucket.count += 1;
+    if (est > 0) {
+      bucket.estSum += est;
+      bucket.estN += 1;
+    }
+    buckets.set(key, bucket);
+    totalRows += 1;
+  }
+  if (!sawSection) filesSkippedNoSection += 1;
+}
+
+const rows = [];
+for (const [key, b] of buckets) {
+  const [phase, domain, decision, appliedBy] = key.split('|');
+  const avgLines = b.estN > 0 ? (b.estSum / b.estN).toFixed(1) : '-';
+  const pct = totalRows > 0 ? ((b.count / totalRows) * 100).toFixed(1) + '%' : '-';
+  rows.push({ phase, domain, decision, appliedBy, count: b.count, avgLines, pct });
+}
+rows.sort((a, b) => a.phase.localeCompare(b.phase) || b.count - a.count);
+
+const headers = ['Phase', 'Domain', 'Decision', 'Applied-by', 'Count', 'Avg-Lines', 'Pct-Total'];
+const widths = headers.map((h, i) => {
+  const colKey = ['phase', 'domain', 'decision', 'appliedBy', 'count', 'avgLines', 'pct'][i];
+  return Math.max(h.length, ...rows.map((r) => String(r[colKey]).length));
+});
+
+function fmtRow(cells) {
+  return cells.map((c, i) => String(c).padEnd(widths[i])).join('  ');
+}
+
+console.log(fmtRow(headers));
+console.log(widths.map((w) => '-'.repeat(w)).join('  '));
+for (const r of rows) {
+  console.log(fmtRow([r.phase, r.domain, r.decision, r.appliedBy, r.count, r.avgLines, r.pct]));
+}
+
+console.log('');
+console.log(`Files parsed: ${filesParsed}  |  Files w/o log section: ${filesSkippedNoSection}  |  Rows: ${totalRows}`);
+
+// Flag candidate violations: inline apply on doc/security/migration domains
+const violationRows = rows.filter(
+  (r) =>
+    r.appliedBy === 'orchestrator' &&
+    (r.domain === 'doc' || r.domain === 'codex-security' || r.domain.startsWith('migration'))
+);
+if (violationRows.length > 0) {
+  console.log('');
+  console.log('⚠  Candidate violations (inline apply on domain-override domains):');
+  for (const r of violationRows) {
+    console.log(`   ${r.phase} | ${r.domain} | applied_by=${r.appliedBy} | count=${r.count}`);
+  }
+}

package/package.json

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