baldart 4.2.1 → 4.2.2

package/CHANGELOG.md

@@ -5,6 +5,16 @@ 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.2.2] - 2026-06-03
+
+**`/new` Phase 0 stops blocking on framework-owned noise: telemetry-only dirty trees and `baldart update`/subtree commits are auto-ignored.** Every batch tripped its own Phase 0 gates: (1) the dirty-tree gate fired on `${paths.metrics}/archive/batch-tracker-*.md` + `skill-runs.jsonl` + `sessions/` — telemetry that Phase 8 writes *after* the merge and never commits, so the next batch always saw a "dirty" tree and forced a stash/commit decision; (2) the divergence gate fired on `.framework/` subtree commits + the `[CHORE] baldart update …` chore, treating expected framework-management divergence as the FEAT-0006 orphan-commit pattern and forcing a push/cherry-pick decision. Both gates now **partition the working tree / the ahead-commits before prompting** and surface only genuine in-progress user work. The FEAT-0006 protection is intact — real orphan commits and real uncommitted work still gate. **PATCH** (bugfix to an existing gate's classification; no new agent/skill/template, no `baldart.config.yml` key — `paths.metrics` already exists).
+
+> **Why.** Phase 0 exists because of a real incident (FEAT-0006: an unpushed orphan commit + diverged trunk caused data loss), so the gates can't be removed. But they were classifying *framework-generated artifacts as if they were user state* — the skill's own Phase 8 telemetry and the `baldart update` subtree commits — and raising a non-decision to the user on every single `/new` run. The fix is surgical classification, not relaxation: the dirty-tree gate filters paths under `$METRICS` (resolved from `paths.metrics`) and gates only on the remainder; the divergence gate reclassifies each ahead commit (subtree merge into `.framework/`, `baldart update`/`add` chore, or `.framework/`-only diff) as framework-management and counts only genuine unpushed commits. Phase 6c's batch-close assertion gets the same reclassification so the noise doesn't re-appear at the end. `/prd` and `/nw` were already lean (read-only pre-flight, branch from `origin/$TRUNK`) and needed no change. Aligns with the standing "respect explicit user intent — no silent confirmation gates for non-decisions" principle.
+
+### Changed
+
+- **`framework/.claude/skills/new/SKILL.md`** — Phase 0 step 0 now resolves `$METRICS` (`paths.metrics`, default `docs/metrics`). Step 3 (dirty-tree gate) partitions `git status --porcelain`, dropping framework telemetry under `$METRICS`; gates only on `$USER_DIRTY`, otherwise logs `Dirty: framework-telemetry-only (auto-ignored)` and proceeds with no `AskUserQuestion`. Step 4 (divergence gate) and Phase 6c step 4 (batch-close divergence assertion) reclassify ahead commits, count only `$GENUINE_AHEAD`, auto-ignore `$FW_SKIPPED` framework-management commits, and branch on `$BEHIND`/`$GENUINE_AHEAD`. Step 5 log template extended with the two new auto-ignored states.
+
 ## [4.2.1] - 2026-06-03
 
 **`/prd` pre-dev audit: `code-reviewer` swapped for `plan-auditor` (card grounding) in the `check-audit` team.** The Step 6 pre-development audit ran `code-reviewer` on backlog `.yml` cards — but `code-reviewer` is built around a *diff* (scope = `git diff --name-only`, diff-simulation pass, completion-report cross-check, line-range/`repro_steps` findings schema, `PASS/FAIL/NEEDS_REWORK` verdict), none of which applies before any code exists. The audit had to re-purpose it with an ad-hoc mandate and override its native output format. `plan-auditor` is the agent purpose-built for this surface (native `.yml` INPUT TYPE DETECTION + BACKLOG CARD ATTACK SURFACE + native `[Target: <field>]` tagging + project memory), so it now fills that slot. **PATCH** (refinement of an existing capability — swaps which already-shipped agent audits cards; no new agent/skill/template, no `baldart.config.yml` key).

package/VERSION

@@ -1 +1 @@
-4.2.1
+4.2.2

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

@@ -141,6 +141,7 @@ Trunk branch: [resolved git.trunk_branch — Phase 0 step 0 populates]
 0. **Feature gate + config resolution (BLOCKING)** — before anything else:
    - Read `features.has_backlog` from `baldart.config.yml`. If it is `false` (or the key is absent and the user confirms there is no backlog), this skill REFUSES to run: print "`/new` operates on backlog cards and requires `features.has_backlog: true` — run `npx baldart configure` to enable." and HALT. Do NOT proceed to step 1.
    - Resolve `$TRUNK` = `git.trunk_branch` from `baldart.config.yml`. **When the key is absent** (consumer updated to ≥4.0.0 without re-running `configure`), do NOT hard-assume `develop` — autodetect the repo's real default branch exactly as worktree-manager does, so `/new` and `nw` agree on the base: `git -C "$MAIN" symbolic-ref --quiet refs/remotes/origin/HEAD` (strip `refs/remotes/origin/`), else the first existing local branch among `develop` / `main` / `master`. A `main`-trunk repo defaulted to `develop` here would diverge from the worktree base `nw` picks and break every `git diff "$TRUNK...HEAD"` gate. Only HALT ("Trunk branch unresolved — run `npx baldart configure`") if nothing resolves. Persist the resolved value as `Trunk branch:` in the tracker `## Worktree` section. **Every later Phase 0 / Phase 6c bash snippet that references the integration trunk MUST use `$TRUNK`, never a baked-in `develop`.** Begin every later consumer with a guard: if `$TRUNK` is empty → HALT with "Trunk branch unresolved — re-read `git.trunk_branch` from the tracker".
+   - Resolve `$METRICS` = `paths.metrics` from `baldart.config.yml` (default `docs/metrics`). This is the framework-owned telemetry directory written by Phase 8 (tracker archive, `skill-runs.jsonl`, `sessions/`). The dirty-tree gate (step 3) reads `$METRICS` to recognise — and never surface — its own telemetry output. Persist it as `Metrics dir:` in the tracker `## Worktree` section.
 
 1. **Resolve `$MAIN`** — the absolute path of the main repo (not a worktree). If `/new` was invoked from inside a worktree, walk up to the parent repo via `git rev-parse --show-superproject-working-tree` or `git worktree list` until you find the non-worktree root. Persist as `Main repo:` in the tracker `## Worktree` section. **Write `$MAIN` to the tracker the moment it is computed** — every later consumer (Phase 6c, Phase 6b) MUST re-read it from the tracker and HALT with "`$MAIN` absent from tracker" if the field is missing or empty, never silently use an undefined `$MAIN` (it does not survive context compaction).
 
@@ -149,11 +150,20 @@ Trunk branch: [resolved git.trunk_branch — Phase 0 step 0 populates]
    git -C "$MAIN" fetch origin --quiet
    ```
 
-3. **Dirty-tree gate (BLOCKING)** — capture the working tree state of the main repo:
+3. **Dirty-tree gate (BLOCKING — framework telemetry is auto-ignored, never surfaced)** — capture the working tree state of the main repo, then **partition it** so the gate fires only on genuine in-progress user work:
    ```bash
-   git -C "$MAIN" status --porcelain
-   ```
-   If the output is non-empty, invoke `AskUserQuestion`:
+   PORCELAIN="$(git -C "$MAIN" status --porcelain)"
+   # Drop framework-owned telemetry THIS skill writes in Phase 8 (tracker archive,
+   # skill-runs.jsonl, sessions/) and never commits. Porcelain lines are "XY path";
+   # paths with special chars are quoted. $METRICS resolved in step 0 (e.g. docs/metrics).
+   USER_DIRTY="$(printf '%s\n' "$PORCELAIN" \
+     | grep -vE "^.{3}\"?${METRICS}/" \
+     | grep -vE "^.{3}\"?${METRICS}\"?$" \
+     | grep -v '^[[:space:]]*$')"
+   ```
+   **Why**: Phase 8 copies the batch tracker into `$METRICS/archive/` and appends to `$METRICS/skill-runs.jsonl` *after* the merge, and never commits them. If those untracked telemetry files tripped this gate, **every batch would block on the previous batch's metrics** — a self-inflicted loop. They are not user work and the user is never asked about them.
+   - If `$PORCELAIN` is non-empty but `$USER_DIRTY` is **empty** (only telemetry under `$METRICS` is dirty) → do **NOT** gate. Write `Dirty: framework-telemetry-only (auto-ignored)` to the tracker and proceed to step 4. No `AskUserQuestion`.
+   - If `$USER_DIRTY` is **non-empty** (genuine uncommitted user work) → invoke `AskUserQuestion`:
    - Question: `"Main repo ($MAIN) ha modifiche non committate prima di partire con la batch. Come procedo?"`
    - Options (max 4):
      1. **"Stash automatico (restore in Phase 6c)"** — `$MAIN` is the main checkout (NOT a worktree), so a stash here is safe. Run `git -C "$MAIN" stash push -u -m "baldart-new-phase0-<FIRST-CARD-ID>-<timestamp>"` and write the **stash MESSAGE label** (`baldart-new-phase0-<FIRST-CARD-ID>-<timestamp>`) to the tracker under `## Workspace Snapshot: <message-label> (created <timestamp>)`. Phase 6c resolves the stash by this message — NEVER by a positional `stash@{N}`, because other stashes pushed during the batch (on the main checkout) would shift the index. Do NOT record `stash@{0}`.
@@ -163,23 +173,40 @@ Trunk branch: [resolved git.trunk_branch — Phase 0 step 0 populates]
 
    Do NOT silently proceed. Do NOT auto-stash without the user picking option 1.
 
-4. **Divergence gate (BLOCKING)** — compare local `$TRUNK` against `origin/$TRUNK` (the trunk resolved in step 0):
+4. **Divergence gate (BLOCKING — framework-management commits do NOT count as orphan commits)** — compare local `$TRUNK` against `origin/$TRUNK` (the trunk resolved in step 0):
    ```bash
-   git -C "$MAIN" rev-list --left-right --count "origin/$TRUNK...$TRUNK"
+   read BEHIND AHEAD <<< "$(git -C "$MAIN" rev-list --left-right --count "origin/$TRUNK...$TRUNK")"
    ```
-   The output is `<behind>\t<ahead>`. Branch on the result:
-
-   - **`0\t0`** — synchronized. Proceed to step 5.
-   - **`N\t0`** (only behind, N > 0) — invoke `AskUserQuestion`:
-     - Question: `"Local $TRUNK è behind origin/$TRUNK di N commit. Come procedo?"`
+   `$BEHIND` / `$AHEAD` are the raw counts. Before branching, **reclassify the ahead commits**: commits produced by `baldart update`/`baldart add` (subtree merges into `.framework/`, the `[CHORE] baldart update …` commit, and the regenerated overlay files they carry) are *expected* divergence, not the FEAT-0006 orphan-commit pattern. Count only **genuine** unpushed commits:
+   ```bash
+   GENUINE_AHEAD=0; GENUINE_LIST=""; FW_SKIPPED=0
+   for sha in $(git -C "$MAIN" rev-list "origin/$TRUNK..$TRUNK"); do
+     subj="$(git -C "$MAIN" log -1 --format=%s "$sha")"
+     # subtree merge (e.g. "Merge commit '…' as '.framework'") or baldart update/add chore
+     if printf '%s' "$subj" | grep -qE "as '\.framework'" || printf '%s' "$subj" | grep -qiE "baldart (update|add)"; then
+       FW_SKIPPED=$((FW_SKIPPED+1)); continue
+     fi
+     # touches ONLY files under .framework/ ? (empty file list = merge commit, handled above)
+     files="$(git -C "$MAIN" show --pretty=format: --name-only "$sha" | grep -v '^$')"
+     if [ -n "$files" ] && ! printf '%s\n' "$files" | grep -qvE '^\.framework/'; then
+       FW_SKIPPED=$((FW_SKIPPED+1)); continue
+     fi
+     GENUINE_AHEAD=$((GENUINE_AHEAD+1)); GENUINE_LIST="$GENUINE_LIST $sha"
+   done
+   ```
+   `$FW_SKIPPED` framework-management commits are auto-ignored (log them — see below). Branch on `$BEHIND` and the **genuine** ahead count `$GENUINE_AHEAD` (NOT the raw `$AHEAD`):
+
+   - **`BEHIND=0` and `GENUINE_AHEAD=0`** — synchronized for `/new`'s purposes. If `$FW_SKIPPED > 0`, write `Divergence: $FW_SKIPPED framework-management commits ahead (auto-ignored — baldart update/subtree)` to the tracker. **No `AskUserQuestion`.** Proceed to step 5.
+   - **`BEHIND>0` and `GENUINE_AHEAD=0`** (only behind) — invoke `AskUserQuestion`:
+     - Question: `"Local $TRUNK è behind origin/$TRUNK di $BEHIND commit. Come procedo?"`
      - Options: `[Fast-forward pull adesso]` / `[Procedi senza pull]` / `[Abort]`.
      - On `Fast-forward pull adesso`: if `$MAIN` HEAD == `$TRUNK`, run `git -C "$MAIN" pull --ff-only origin "$TRUNK"`; otherwise log "main HEAD is `<branch>` — fetch already updated `refs/remotes/origin/$TRUNK`, local `$TRUNK` ref will be reconciled in Phase 6c".
-   - **`0\tM`** (only ahead, M > 0 — UNPUSHED LOCAL COMMITS, this is the FEAT-0006 pattern) — invoke `AskUserQuestion`:
-     - Question: `"Local $TRUNK è ahead di origin/$TRUNK di M commit (commit locali non pushati). Cosa faccio?"`
-     - Show the commit list inline: `git -C "$MAIN" log --oneline "origin/$TRUNK..$TRUNK"`.
+   - **`BEHIND=0` and `GENUINE_AHEAD>0`** (genuine UNPUSHED LOCAL COMMITS, this is the FEAT-0006 pattern) — invoke `AskUserQuestion`:
+     - Question: `"Local $TRUNK è ahead di origin/$TRUNK di $GENUINE_AHEAD commit locali non pushati (esclusi $FW_SKIPPED commit di gestione framework). Cosa faccio?"`
+     - Show **only the genuine** commits inline: `git -C "$MAIN" show -s --oneline $GENUINE_LIST`.
      - Options: `[Push adesso (git push origin $TRUNK)]` / `[Cherry-pick a parte e continua]` / `[Lascia così e procedi (lo gestisco io)]` / `[Abort]`.
-   - **`N\tM`** (diverged both ways) — invoke `AskUserQuestion`:
-     - Question: `"Local $TRUNK è diverged da origin/$TRUNK: N behind, M ahead. Servono entrambe le riconciliazioni. Come procedo?"`
+   - **`BEHIND>0` and `GENUINE_AHEAD>0`** (diverged both ways) — invoke `AskUserQuestion`:
+     - Question: `"Local $TRUNK è diverged da origin/$TRUNK: $BEHIND behind, $GENUINE_AHEAD genuine ahead. Servono entrambe le riconciliazioni. Come procedo?"`
      - Options: `[Rebase local $TRUNK su origin/$TRUNK]` / `[Mostrami i commit e fammi decidere]` / `[Abort]`.
 
 5. **Log and proceed** — write to the tracker:
@@ -188,8 +215,8 @@ Trunk branch: [resolved git.trunk_branch — Phase 0 step 0 populates]
    Status: PASS
    Main repo: $MAIN
    Trunk branch: $TRUNK
-   Dirty: <none | stashed: <message-label> | user-override>
-   Divergence (local…origin/$TRUNK): <0\t0 | resolved: ff-pull | resolved: pushed | user-deferred>
+   Dirty: <none | framework-telemetry-only (auto-ignored) | stashed: <message-label> | user-override>
+   Divergence (local…origin/$TRUNK): <0\t0 | framework-mgmt-only (auto-ignored: $FW_SKIPPED) | resolved: ff-pull | resolved: pushed | user-deferred>
    Completed: <timestamp>
    ```
    If any step ended in HALT, set `Status: HALT` and stop — do NOT continue to `## Pre-flight (once)`.
@@ -1868,18 +1895,19 @@ The most common failure mode is leaving cards IN_PROGRESS after merge. This crea
 
 4. **Divergence assertion (BLOCKING — this catches the FEAT-0006 orphan-commit pattern)**. `$MAIN` and `$TRUNK` are read from the tracker (`## Worktree` section); HALT if either is absent/empty.
    ```bash
-   git -C "$MAIN" rev-list --left-right --count "origin/$TRUNK...$TRUNK"
+   read BEHIND AHEAD <<< "$(git -C "$MAIN" rev-list --left-right --count "origin/$TRUNK...$TRUNK")"
    ```
-   If the output is anything other than `0\t0`:
-   - **Ahead only (M > 0, unpushed commits)** — invoke `AskUserQuestion`:
-     - Question: `"Local $TRUNK ha M commit non pushati su origin/$TRUNK al termine del batch. Lista: <git log --oneline origin/$TRUNK..$TRUNK>. Cosa faccio?"`
+   Compute `$GENUINE_AHEAD` / `$GENUINE_LIST` / `$FW_SKIPPED` with the **exact same reclassification loop as Phase 0 step 4** (framework-management commits — subtree merges into `.framework/`, `baldart update`/`add` chores, `.framework/`-only commits — are auto-ignored, NOT orphan commits). Then branch on `$BEHIND` and `$GENUINE_AHEAD`:
+   - **`BEHIND=0` and `GENUINE_AHEAD=0`** — synchronized. If `$FW_SKIPPED > 0`, log `Divergence: $FW_SKIPPED framework-management commits ahead (auto-ignored)` and proceed. No `AskUserQuestion`.
+   - **Ahead only (`GENUINE_AHEAD > 0`, genuine unpushed commits)** — invoke `AskUserQuestion`:
+     - Question: `"Local $TRUNK ha $GENUINE_AHEAD commit genuini non pushati su origin/$TRUNK al termine del batch (esclusi $FW_SKIPPED di gestione framework). Lista: <git show -s --oneline $GENUINE_LIST>. Cosa faccio?"`
      - Options: `[Push adesso (git push origin $TRUNK)]` / `[Cherry-pick selettivo su origin/$TRUNK]` / `[Reset --hard origin/$TRUNK (richiede conferma esplicita, DISTRUTTIVO)]` / `[Halt con stato preservato]`.
      - On `Reset --hard origin/$TRUNK` re-ask `AskUserQuestion` to confirm: `"Confermi reset --hard? I commit <list> verranno persi se non pushati altrove."` Solo dopo conferma esplicita esegui il reset.
-   - **Behind only (N > 0)** — invoke `AskUserQuestion`:
-     - Question: `"Local $TRUNK è behind origin/$TRUNK di N commit (qualcuno ha pushato durante il batch). Faccio ff-pull adesso?"`
+   - **Behind only (`BEHIND > 0`, `GENUINE_AHEAD=0`)** — invoke `AskUserQuestion`:
+     - Question: `"Local $TRUNK è behind origin/$TRUNK di $BEHIND commit (qualcuno ha pushato durante il batch). Faccio ff-pull adesso?"`
      - Options: `[Fast-forward pull]` / `[Lascia behind (lo gestisco io)]`.
-   - **Diverged both ways** — invoke `AskUserQuestion`:
-     - Question: `"Local $TRUNK è diverged (N behind, M ahead). Servono entrambe le riconciliazioni. Come procedo?"`
+   - **Diverged both ways (`BEHIND > 0` and `GENUINE_AHEAD > 0`)** — invoke `AskUserQuestion`:
+     - Question: `"Local $TRUNK è diverged ($BEHIND behind, $GENUINE_AHEAD genuine ahead). Servono entrambe le riconciliazioni. Come procedo?"`
      - Options: `[Rebase local $TRUNK su origin/$TRUNK]` / `[Mostrami i commit locali e decidiamo]` / `[Halt]`.
 
 5. **Restore Phase 0 stash (if any)** — read the tracker for `## Workspace Snapshot: <message-label>`:

package/package.json

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