baldart 4.96.0 → 4.97.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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.97.0] - 2026-07-02
+
+**Change Tiers — a real Light lane, so ordinary edits stop triggering the heavy machinery.** The root primitives forced plan mode on *any* non-trivial task, a `plan-auditor` + `doc-reviewer` review gate on *every* non-trivial plan, mandatory delegation to a domain agent, and (amplified by project overlays) a worktree + backlog card whenever more than a few files were touched — so even a small direct edit spun up the full orchestration. Root cause: there were only two tiers (Trivial vs everything-else-is-Heavy); no genuine middle lane.
+
+- **New `## Change Tiers` section in the `AGENTS.md` primitive** (cross-tool SSOT, read by Claude + Codex) defines **Trivial / Light / Heavy**, and the *tier* — not raw file count — decides whether the heavy machinery fires. Default is **Light; when in doubt → Light**.
+- **Light** (the new default for most work): any change that hits **no Heavy trigger**, even multi-file within one coherent area → implemented **directly on the current branch**, no plan mode, no plan-review, no worktree, no card.
+- **Heavy** (aggressive calibration): escalate ONLY for a new DB schema/migration, a new external dependency, a new API contract/route or domain entity, a wide/cross-module refactor, or work parallel to other sessions on shared files → full machinery.
+- The plan-review MUST, the delegation MUST, and the Git Workflow worktree rule in `AGENTS.md` are now scoped to **Heavy**; the `CLAUDE.md` primitive Plan Mode section likewise fires only for Heavy (Light/Trivial skip plan mode + review + mandatory delegation). Primitives bumped: `AGENTS.md` 1.5.0 → **1.6.0**, `CLAUDE.md` 1.2.0 → **1.3.0**.
+
+**MINOR** — behavior/posture change to shipped primitives, no install-layout change. **Codex parity: portable** — pure prose in the shared `AGENTS.md` skeleton; Codex reads the same tiers to decide agent-spawn / worktree / card. **Not a `baldart.config.yml` key** → the schema-change propagation rule does NOT apply. Consumers pick it up on `baldart update` (regenerated root primitives); project overlays may add project-specific Heavy triggers.
+
 ## [4.96.0] - 2026-07-02
 
 **Protected branch decoupled from the integration trunk — `git.protected_branch`.** The root `AGENTS.md` primitive expressed the "NEVER push directly to X" MUST via `{{ git.trunk_branch }}`, conflating two distinct roles that in a two-branch gitflow are different branches: the *integration trunk* (worktree base + feature PR target in `/prd` + `/new`) and the *protected branch* (production/release line that must not receive direct pushes). A consumer with `trunk_branch: develop` therefore had its agents (Claude + Codex) refuse a direct `develop` push — even though `develop` was the integration branch they push to and `main` was the truly-protected line. `trunk_branch` could not simply be flipped to `main` because it also drives worktree creation (`update.js`), which must branch from `develop`.

package/VERSION

@@ -1 +1 @@
-4.96.0
+4.97.0

package/framework/templates/primitives/AGENTS.CHANGELOG.md

@@ -4,6 +4,21 @@ Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://sem
 Questo è il changelog INTERNO dello skeleton spedito (`primitive_version`), separato dal
 file `AGENTS.md` generato nel consumer e indipendente dal `VERSION` del framework.
 
+## 1.6.0 — 2026-07-02
+
+- **Change Tiers — a real Light lane between Trivial and Heavy**: new `## Change Tiers`
+  section defines Trivial / Light / Heavy, and the tier (NOT raw file count) now decides
+  whether the heavy machinery fires. The plan-review MUST is scoped to **Heavy** plans (was
+  "any non-trivial plan → `plan-auditor` + `doc-reviewer`"); the delegation MUST is scoped to
+  **Heavy** implementation (Light changes MAY be implemented directly inline); the Git
+  Workflow worktree rule fires for **Heavy** work on a new branch (Light goes on the current
+  branch). Heavy triggers (aggressive calibration): new DB schema/migration, new external
+  dependency, new API contract/route or domain entity, wide/cross-module refactor, or work
+  parallel to other sessions on shared files. Default is **Light; when in doubt → Light**.
+  Removes the "everything is non-trivial → plan mode + review + delegate + worktree + card"
+  friction on ordinary edits. Cross-tool: pure prose in the shared skeleton — portable
+  (Claude + Codex; Codex reads the same tiers to decide agent-spawn / worktree / card).
+
 ## 1.5.0 — 2026-07-02
 
 - **Protected branch decoupled from the integration trunk**: the "NEVER push directly"

package/framework/templates/primitives/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- baldart-primitive: name=AGENTS primitive_version=1.5.0
+<!-- baldart-primitive: name=AGENTS primitive_version=1.6.0
      This is the SHIPPED SKELETON. The writer (src/utils/root-primitives.js) strips
      this banner, resolves every {{ slot }} / {{> partial }} / {{#flag}} from
      baldart.config.yml (+ package.json/README), merges .baldart/overlays/AGENTS.md,
@@ -33,16 +33,19 @@ mechanics — this file remains the single source of truth for the protocol.
   diff). Contract + per-profile scoping: `agents/analysis-profiles.md`. Only if NEITHER
   invocation mechanism exists, degrade explicitly to inline retrieval
   (code-graph → LSP → Grep) and SAY SO.
-- MUST have any non-trivial plan reviewed BEFORE presenting it for approval — run
-  `plan-auditor` + `doc-reviewer` (in parallel), incorporate their feedback, and note in the
-  plan that the review gate was honored. Present the ALREADY-reviewed plan, never a raw one.
-  (Claude Code enforces this inside plan mode, before `ExitPlanMode` — see `CLAUDE.md`.)
-- MUST delegate implementation to the domain agent — plan and delegate, do NOT write
-  substantial code inline: **code / logic / tests → `coder`**; **UI (components, pages,
+- MUST have any **Heavy** plan (see § Change Tiers) reviewed BEFORE presenting it for
+  approval — run `plan-auditor` + `doc-reviewer` (in parallel), incorporate their feedback,
+  and note in the plan that the review gate was honored. Present the ALREADY-reviewed plan,
+  never a raw one. (Claude Code enforces this inside plan mode, before `ExitPlanMode` — see
+  `CLAUDE.md`.) **Light** and **Trivial** changes need no plan and no review — implement them
+  directly.
+- MUST delegate **Heavy** implementation to the domain agent — plan and delegate, do NOT
+  write substantial code inline: **code / logic / tests → `coder`**; **UI (components, pages,
   styling, visual output) → `ui-expert`**. Same dual-tool invocation as `codebase-architect`
-  (Claude Code: Task tool `subagent_type`; Codex: custom agent by name). Every other agent
-  (code-reviewer, doc-reviewer, qa-sentinel, security-reviewer, …) routes via
-  `.claude/agents/REGISTRY.md`.
+  (Claude Code: Task tool `subagent_type`; Codex: custom agent by name). For a **Light**
+  change the orchestrator MAY implement directly inline (or still delegate at its discretion
+  — e.g. for volume). Every other agent (code-reviewer, doc-reviewer, qa-sentinel,
+  security-reviewer, …) routes via `.claude/agents/REGISTRY.md`.
 - MUST NOT silently substitute a different agent when an invocation returns empty / times
   out / is denied — STOP, report verbatim, and wait. Never auto-route to a generic agent.
 - MUST NOT work on files another agent has claimed; parallel work only on independent areas.
@@ -91,14 +94,34 @@ mechanics — this file remains the single source of truth for the protocol.
   entries older than 7 days to `work-history.md`.
 {{/has_project_status}}
 
+## Change Tiers
+
+Every change is one of three tiers. The tier — NOT raw file count — decides whether the heavy
+machinery (plan mode, plan review, delegation, worktree, backlog card) applies. **When in
+doubt, treat it as Light** and escalate only when a Heavy trigger is actually present.
+
+- **Trivial** — a one-liner, typo, or obvious bug with a clear fix. Just do it.
+- **Light** — the default for most work. Any change that does **not** hit a Heavy trigger,
+  even if it spans several files within one coherent area. → Implement **directly on the
+  current branch**: no plan mode, no plan-review gate, no worktree, no backlog card. The
+  orchestrator may edit inline or delegate for volume. Docs stay in sync and the pre-commit
+  gates still run.
+- **Heavy** — escalate ONLY when the change: introduces a new DB schema / migration; adds a
+  new external dependency; adds a new API contract / route or a new domain entity; is a wide
+  or cross-module refactor; or runs in parallel with other agents/sessions on shared files.
+  → Full machinery: plan mode → reviewed plan (`plan-auditor` + `doc-reviewer`) → delegation
+  to the domain agent → a git **worktree** (`/nw`) → a backlog card (when the backlog feature
+  is on). Project overlays may add project-specific Heavy triggers.
+
 ## Git Workflow
 
 Branch naming: `{{ git.feature_prefix }}/<CARD-ID>-slug` (local), `codex/…` or `claude/…`
 (cloud agents), `hotfix/<ID>-slug` (production fixes). Branches are created by the
 orchestrator (`/nw`, `/new`) or the user — **never by the `coder` agent** (it implements on
-the branch it was spawned on). For a NEW branch, prefer a git **worktree** (`/nw`): the
-orchestrator MUST NOT run `git switch` / `checkout -b` / `branch` on the shared main
-checkout (other sessions share it). Stage explicit filenames only; never bundle unrelated changes.
+the branch it was spawned on). **Light** changes go directly on the current branch. **Heavy**
+work on a NEW branch uses a git **worktree** (`/nw`) — the orchestrator MUST NOT run
+`git switch` / `checkout -b` / `branch` on the shared main checkout (other sessions share it).
+Stage explicit filenames only; never bundle unrelated changes.
 
 ## Workflow Gates
 

package/framework/templates/primitives/CLAUDE.CHANGELOG.md

@@ -4,6 +4,13 @@ Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://sem
 Changelog INTERNO dello stub spedito (`primitive_version`), separato dal `CLAUDE.md`
 generato nel consumer e indipendente dal `VERSION` del framework.
 
+## 1.3.0 — 2026-07-02
+
+- Plan Mode scoped to **Heavy** changes (see `AGENTS.md` § Change Tiers): Light and Trivial
+  changes now explicitly skip plan mode, the plan-review gate, and mandatory delegation —
+  implemented directly. "When in doubt → Light." Removes the plan-mode-for-any-non-trivial-
+  task friction on ordinary edits. Mirrors the AGENTS.md primitive 1.6.0 Change Tiers.
+
 ## 1.2.0 — 2026-07-02
 
 - Plan Mode: the `codebase-architect` pre-plan invocation now passes the matching

package/framework/templates/primitives/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- baldart-primitive: name=CLAUDE primitive_version=1.2.0
+<!-- baldart-primitive: name=CLAUDE primitive_version=1.3.0
      SHIPPED SKELETON. The writer strips this banner, resolves {{ slot }}/{{#flag}} from
      baldart.config.yml, merges .baldart/overlays/CLAUDE.md, stamps a baldart-generated
      marker, and writes the result to the repo root.
@@ -14,8 +14,11 @@ SSOT, not restated here. Below are the **Claude-native mechanics only**.
 
 ## Plan Mode (Claude-native)
 
-- Enter plan mode (`EnterPlanMode`) for any non-trivial task before writing code.
-  Trivial = single-line fix / typo / obvious bug.
+Plan mode is for **Heavy** changes only (see `AGENTS.md` § Change Tiers). **Light** and
+**Trivial** changes skip plan mode, the plan-review gate, and mandatory delegation — implement
+them directly. When in doubt, treat it as Light. For a Heavy task:
+
+- Enter plan mode (`EnterPlanMode`) before writing code.
 - Invoke `codebase-architect` before writing the plan — never plan blind. Pass the
   matching `PROFILE=<feature|bug|impact|discovery|ui|baseline>` token (the profile
   vocabulary and routing live in `AGENTS.md` § Non-negotiables and

package/package.json

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