baldart 4.94.0 → 4.96.0

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).
 
+## [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`.
+
+- **New optional config key `git.protected_branch`** — the branch the "never push directly" rule protects. **Defaults to `git.trunk_branch`** when omitted, so single-trunk repos are byte-unchanged; a two-branch gitflow sets it explicitly (e.g. `protected_branch: main` while `trunk_branch: develop` stays the worktree base + PR target).
+- **Primitive `AGENTS.md` skeleton → 1.5.0**: the push MUST now resolves `{{ git.protected_branch }}` and explicitly permits direct pushes to other branches (including the integration trunk when it differs) when the owner authorizes it.
+- **Slot resolution** (`src/utils/root-primitives.js`): `git.protected_branch` resolves to `git.protected_branch || git.trunk_branch || 'main'`.
+- **Schema-change propagation** (per the rule): template (`baldart.config.template.yml` — new commented key under `git:`), `configure` (new `detectProtectedBranch` probe + serialized `git.protected_branch` + `_probes`), `update` detector (already diffs all `git.*` keys → surfaces `git.protected_branch`; added a dedicated advisory), CHANGELOG. No doctor diagnostic needed (the update advisory + configure autodetect cover it).
+
+**MINOR** — new optional config key, back-compat default, no install-layout change. **Codex parity: portable** — pure slot resolution in the shared `AGENTS.md` skeleton (transpiled to `.codex/agents/*` unchanged; the generated `AGENTS.md` is the cross-tool SSOT read by both runtimes).
+
+## [4.95.0] - 2026-07-02
+
+**`/prd` — applier economico + EARS+verify (i due interventi strutturali dal forensics della deep analysis).**
+
+- **Apply dei finding delegato** (`prd-card-writer` `MODE: apply-findings` — un agente + token, pattern analysis-profiles v4.94.0): l'orchestratore `/prd` non edita più YAML a piena finestra (misurato: le fasi meccaniche erano il 48% del costo di un run reale, ~48 Edit a ~663k cache-read/chiamata). L'applier gira in contesto fresco (Claude: override `model: sonnet`; Codex: by-name), riceve tutto BY PATH, applica solo campi `[Target:]` con grounding obbligatorio, ESEGUE `validate-card-baseline.js --prd` + `stamp-holistic-audit.js`, ritorna compact; `audit-phase.md` 6.9 = delega thin + drift guard + fallback inline visibile. Verificato con spawn reale su fixture.
+- **AC in grammatica EARS** (child/standalone; SSOT `card-schema.md` § "Acceptance-criteria grammar"): binari per forma (5 pattern + `SHALL CONTINUE TO`), ban-list verbi vaghi, BLOCKER in `--prd`; card legacy mai retro-bloccate.
+- **`ac_verification`** — oracolo eseguibile per-AC definito a planning time (o `manual:` esplicito), authoring groundato (mai comandi inventati), eseguito da `/new` Phase 2.5 (step 4b — exit status = evidenza primaria); `qa-sentinel` intatto per contratto. Enforcement WARN-first; fixtures CI (Check D).
+
+**MINOR** — capability su skill/agent/moduli condivisi; nessun cambio di layout install. **No new `baldart.config.yml` key**; la propagazione dello schema CARD viaggia completa nella release (matrice + template + writer + validator + consumer + attack-surface — pattern v4.35.0). **Codex parity: portable.**
+
 ## [4.94.0] - 2026-07-02
 
 **Analysis profiles — `codebase-architect` specializzato per-tipo-di-analisi, un solo agente, un solo SSOT.** L'assessment dei ~50 callsite reali ha mostrato che "capire il codebase" copre 6 lavori diversi (grounding pre-implementazione, tracing di un bug, blast-radius, contesto di planning, inventario UI/design-system, baseline di review) serviti da UN prompt monolitico (~455 righe caricate a ogni spawn) con la conoscenza di specializzazione dispersa nei prompt dei chiamanti (dual-SSOT: il template di `context-primer` ri-dichiarava la search strategy dell'agente). Fix architetturale, stesso meccanismo di `OUTPUT=terse`:

package/VERSION

@@ -1 +1 @@
-4.94.0
+4.96.0

package/framework/.claude/agents/REGISTRY.md

@@ -35,7 +35,7 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 | **hyper-gamification-designer** | Design | Analyze game features and retention mechanics | Progression, reward loops | No | MDA analysis, economy balance |
 | **remotion-animator-orchestrator** | Design | Create Remotion video animations | Motion graphics, asset coordination | Yes | Remotion, visual agent coordination |
 | **prd** | Product | Create PRDs, plans, and backlog cards | Requirements, execution planning | No | PRD writing, backlog management |
-| **prd-card-writer** | Product | Generate atomic backlog cards from approved PRD | Card YAML, traceability, parallel groups | Yes | Backlog writing, dependency analysis |
+| **prd-card-writer** | Product | Generate atomic backlog cards from approved PRD; `MODE: apply-findings` = fresh-context applier of audit findings to card YAML (spawned by /prd Step 6.9, sonnet override) | Card YAML, traceability, parallel groups | Yes | Backlog writing, dependency analysis |
 | **onboarding-architect-lead** | Product | Design/improve user onboarding experiences | Activation flows, experiments | No | Onboarding research, metrics |
 | **website-orchestrator** | Product | Coordinate multi-agent website development | Project orchestration | No | Phase management, quality gates |
 | **senior-researcher** | Research | Comprehensive research on technical topics | Evidence-based analysis | Yes | Web search, citations |

package/framework/.claude/agents/prd-card-writer.md

@@ -476,7 +476,20 @@ Every card MUST include ALL fields from the template:
 - `context` (background + PRD reference)
 - `scope` (summary, users, value)
 - `requirements` (concrete, specific)
-- `acceptance_criteria` (testable `[ ] [AC-N]` items)
+- `acceptance_criteria` (testable `[ ] [AC-N]` items — **EARS grammar MANDATORY on child/
+  standalone cards**: the clause matches one of `THE SYSTEM SHALL …` / `WHEN … THE SYSTEM
+  SHALL …` / `WHILE …` / `WHERE …` / `IF … THEN THE SYSTEM SHALL …` (+ `SHALL CONTINUE TO`
+  for non-regression). Body in the project language, EARS keywords in English. NO vague
+  verbs ("correttamente", "properly", "as expected", … — the `--prd` validator ban-list
+  BLOCKS them): name the observable behavior. SSOT + worked example: `card-schema.md`
+  § "Acceptance-criteria grammar (EARS)". Epic AC-EPIC roll-ups are exempt.)
+- `ac_verification` (OPTIONAL map `AC-N → executable oracle`) — **grounding rule, same class
+  as the Field Grounding Rule**: write a command ONLY if you verified it exists (an npm
+  script in `package.json`, a command in `toolchain.commands.*`, a cited test file that
+  exists — Grep/Read to confirm). NEVER invent commands. Not automatable → explicit
+  `manual: <what a human checks>`. Genuinely undecidable → `[NEEDS CLARIFICATION: …]`.
+  Non-manual oracles SHOULD also appear in `validation_commands` (the validator warns on
+  drift). Consumed by `/new` Phase 2.5, which EXECUTES them.
 - `definition_of_done` (checklist including doc invariants). **When `features.has_i18n: true`** AND the
   card introduces user-facing strings, the DoD MUST carry an i18n-completeness line — NOT merely "strings
   via `t()` + registered", but: *"new keys authored in the source locale + the i18n context registry (by
@@ -724,3 +737,97 @@ Return to the caller a structured summary:
 - Cross-reference every requirement against the PRD source section
 - Verify file paths in `files_likely_touched` exist in the codebase (use Glob to check)
 - Count total files across all cards to verify no file is assigned to conflicting cards without a conflict edge
+
+## MODE: apply-findings (audit-fix applier — invoked by `/prd` audit-phase Step 6.9)
+
+**Trigger:** the invocation prompt contains `MODE: apply-findings`. In this mode you do NOT
+author new cards — you apply an audit's consolidated findings to EXISTING card YAML files.
+(Same one-agent+token mechanism as `PROFILE=` / `OUTPUT=terse`: a mode is a parameter, not a
+twin agent.)
+
+**Why this mode exists (measured):** the `/prd` orchestrator used to apply findings inline at
+full context window (~48 Edits at ~663k cache-read per call — the mechanical phases were 48%
+of a real run's cost). In a fresh subagent context the same work costs a fraction. On Claude
+the caller spawns this mode with a `model: sonnet` override (batch card AUTHORING keeps the
+frontmatter model); on Codex the by-name agent inherits the session model — the primary
+enabler is the fresh context + structured I/O, not the model tier.
+
+**Inputs (all BY PATH — never pasted content):**
+- `REPORT_FILE` — the consolidated audit report (audit-phase Step 6.7 format: findings grouped
+  per card, each tagged `(Severity: HIGH/MEDIUM/LOW)` + `[Target: <field>]`)
+- `CARD_PATHS` — the card YAML files to edit
+- `AUDITED_AT` / `AUDITED_COMMIT` / `AUDITED_SET` — the run-level provenance values
+  (audit-phase § "Holistic-audit provenance stamp")
+- `VALIDATOR` — path of `validate-card-baseline.js`; `STAMPER` — path of `stamp-holistic-audit.js`
+
+**Workflow:**
+1. Read the report; group findings per card ID.
+2. Per card, apply HIGH first, then MEDIUM, per the FIELD MAPPING table below:
+   - Edit ONLY the field named by each finding's `[Target: <field>]` tag. NEVER touch a field
+     no finding targets; NEVER "improve" untargeted content. The Field Grounding Rule above
+     binds here too (no invented field names).
+   - A finding that genuinely requires a human decision → do NOT apply; record it as `[MANUAL]`.
+   - A finding whose suggested content is UNGROUNDED (a path that doesn't exist in the repo,
+     a command not in the project's convention) or ALREADY SATISFIED by the card → do NOT
+     apply it as-is; ground it against the repo first (Glob/Grep), apply the grounded form,
+     or record it in the audit trail as `already-satisfied` / `ungrounded (<why>)`.
+   - LOW findings: audit-trail note only — no structured-field edits.
+   - Append the audit trail to `notes` (format below).
+3. **EXECUTE** `node <VALIDATOR> --prd <card>` on every edited card — exit 0 required. On
+   failure, fix your own edit and re-run (max 2 attempts, then report that card as
+   `validator: FAIL` with the error output — never ship a silently-invalid card).
+4. **EXECUTE** the stamper ONCE for the whole set:
+   `node <STAMPER> --at <AUDITED_AT> --commit <AUDITED_COMMIT> --set <AUDITED_SET> <CARD_PATHS>`
+5. Return the COMPACT summary below. Do NOT echo card bodies or the report back.
+
+### FIELD MAPPING (Target tag → card field → action)
+
+| Target tag | Card field | Action |
+|---|---|---|
+| `[Target: requirements]` | `requirements` | Append missing requirement or rewrite existing one |
+| `[Target: acceptance_criteria]` | `acceptance_criteria` | Append new `"[ ] [AC-N] ..."` item or rewrite vague AC |
+| `[Target: definition_of_done]` | `definition_of_done` | Append new `"[ ] ..."` item |
+| `[Target: files_likely_touched]` | `files_likely_touched` | Append missing path (no duplicates) |
+| `[Target: depends_on]` | `depends_on` | Append missing card ID |
+| `[Target: git_strategy]` | `git_strategy` | Replace `TBD` with `feat/<CARD-ID>-<slug> from ${git.trunk_branch}` |
+| `[Target: areas]` | `areas` | Add missing area key/value |
+| `[Target: unknowns]` | `unknowns` | Append new `[U-N] UNKNOWN: ...` entry |
+| `[Target: existing_patterns]` | `existing_patterns` | Append missing pattern reference or fix stale line_range/anchor_text |
+| `[Target: validation_commands]` | `validation_commands` | Append missing verification command |
+| `[Target: anti_patterns]` | `anti_patterns` | Append missing DO NOT constraint |
+| `[Target: scope_boundaries]` | `scope_boundaries` | Add missing in_scope or out_of_scope item |
+| `[Target: input_output_examples]` | `input_output_examples` | Append missing scenario or fix incorrect example |
+| `[Target: error_handling]` | `error_handling` | Append missing failure mode or fix incorrect action |
+| `[Target: reuse_analysis]` | `reuse_analysis` | Add missing reuse opportunity or correct file path |
+| `[Target: notes]` | `notes` | Audit trail only |
+
+### Severity policy
+
+- **HIGH**: MUST apply. Card cannot be safely implemented without these.
+- **MEDIUM**: SHOULD apply. Skip only if human judgment needed (mark `[MANUAL]`).
+- **LOW**: Do NOT edit structured fields. Audit trail note only.
+
+### Audit trail in `notes`
+
+After applying all edits to a card, append to its `notes`:
+
+```yaml
+## Applied by quality audit — YYYY-MM-DD
+Applied N findings to structured fields (H high, M medium).
+Manual review needed: [list [MANUAL] items, or "none"].
+```
+
+### Return contract (COMPACT — the ONLY output)
+
+```
+APPLY-FINDINGS DONE
+- <CARD-ID>: applied <H> high / <M> medium; manual: [<finding titles> | none]; validator: PASS|FAIL
+- ...
+stamp: <the stamper's one-line summary>
+```
+
+### Boundaries (mode-specific)
+
+Read-only outside the card files; no Task/Agent spawns; no git commits/staging (the
+orchestrator's Step 7 owns git); no card creation, deletion, or renaming; no edits to
+fields not targeted by a finding.

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

@@ -54,6 +54,15 @@ Before triggering any review, you MUST verify that the coder agent implemented *
    index of WHERE to look; you still verify independently (do NOT trust its `status` alone), just
    without pulling entire files inline.
 
+   **4b. Per-AC executable oracles (`ac_verification` — EXECUTE, don't judge).** When the card
+   carries an `ac_verification` map (card-schema.md § "Acceptance-criteria grammar (EARS) +
+   per-AC oracles"), an AC whose oracle is NOT `manual:` is verified by **running the command**
+   — the exit status is the PRIMARY evidence for that row (`Done` on expected exit, `Missing/
+   Partial` otherwise, with the command + exit code in the Evidence column). Reading-based
+   judgment then covers only `manual:` oracles, oracle-less ACs, and the non-AC requirement
+   rows. A failing oracle is never argued around: either the implementation is incomplete
+   (gap-fixer path) or the oracle itself is stale — surface which, never silently reclassify.
+
    **Verification depth per requirement type:**
    - **"Create endpoint/route"** → verify: route file exists, handler has correct HTTP method,
      request validation present, response shape matches requirement, auth middleware applied.

package/framework/.claude/skills/prd/CHANGELOG.md

@@ -6,6 +6,17 @@ Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://sem
 
 - **Analysis-profile contract (framework v4.94.0)**: the discovery-loop targeted architect question now passes `PROFILE=discovery`, and the Step 2 ISA scan passes `PROFILE=impact` (structural tier primary) — per `framework/agents/analysis-profiles.md`. Prompt semantics otherwise unchanged.
 
+## 1.3.0 — 2026-07-02
+
+**Applier economico + pacchetto EARS+verify** — i due interventi strutturali dal forensics (48% del costo nelle fasi meccaniche; gate-prosa aggirabili):
+
+- **`MODE: apply-findings` su `prd-card-writer`** (un agente + token, pattern analysis-profiles — mai un twin): l'apply dei finding di audit esce dall'orchestratore (che non edita più YAML). L'applier riceve tutto BY PATH, applica solo campi `[Target:]`, grounding obbligatorio (path/comandi verificati, mai inventati), marca `[MANUAL]` senza decidere, ESEGUE validator `--prd` + stamper, ritorna compact. `audit-phase.md` Step 6.9 = delega thin + drift guard `git diff --stat` + fallback inline visibile. Field-mapping/severity/audit-trail SPOSTATE nel corpo agente. Testato con spawn reale su fixture.
+- **Grammatica EARS sugli AC child/standalone** (SSOT: `card-schema.md` § "Acceptance-criteria grammar"): 5 pattern (`THE SYSTEM SHALL` / `WHEN` / `WHILE` / `WHERE` / `IF…THEN`) + `SHALL CONTINUE TO`; keyword inglesi, corpo nella lingua del progetto; ban-list verbi vaghi. BLOCKER nel validator `--prd` — le card legacy non sono mai retro-bloccate (il baseline check di `/new` non applica EARS). AC-EPIC esenti.
+- **`ac_verification`** (mappa opzionale `AC-N → oracolo eseguibile` o `manual:`): authoring groundato (comando scritto solo se verificato esistente — classe Field Grounding Rule), consumo in `/new` Phase 2.5 che ESEGUE gli oracoli non-manual (exit status = evidenza primaria; `qa-sentinel` deliberatamente NON è il consumer — AC verification fuori dal suo contratto). Enforcement WARN-first (hard-gate solo dopo telemetria). Cross-check drift con `validation_commands`.
+- Validator: canale warnings separato (mai exit 1 da un WARN); fixtures EARS nel self-test CI (`check-card-baseline.js` Check D).
+
+Codex parity: portable (token in prosa agente → transpile TOML; script zero-dep; prosa condivisa).
+
 ## 1.2.0 — 2026-07-02
 
 **Gate-hygiene wave** — dai driver misurati sul forensics di una sessione /prd reale (61.6M token; 48% del costo in fasi meccaniche a piena finestra; una famiglia di card spedita con zero audit-trail; ~20 righe di progress bar × 30+ messaggi):

package/framework/.claude/skills/prd/assets/card-template.yml

@@ -85,8 +85,12 @@ existing_patterns:
 anti_patterns:
   - "DO NOT {{specific prohibited action — be concrete, not generic}}"
 
+# EARS grammar (card-schema.md § "Acceptance-criteria grammar"): the clause matches one of
+# THE SYSTEM SHALL … / WHEN … THE SYSTEM SHALL … / WHILE … / WHERE … / IF … THEN THE SYSTEM SHALL …
+# Body in the project language, EARS keywords in English. No vague verbs (banned by the validator).
 acceptance_criteria:
-  - "[ ] [AC-1] {{Testable criterion}}"
+  - "[ ] [AC-1] WHEN {{trigger}} THE SYSTEM SHALL {{observable behavior}}"
+  - "[ ] [AC-2] IF {{error condition}} THEN THE SYSTEM SHALL {{recovery behavior}}"
 
 # --- Validation Commands (OPTIONAL — include for cards with testable outputs) ---
 # Executable commands the agent runs for self-verification after implementation.
@@ -98,6 +102,14 @@ validation_commands:
     expect: "exit 0"
   - cmd: "{{verification command, e.g. grep -c 'pattern' src/file.tsx}}"
     expect: "{{expected: 'exit 0', '>= N', 'contains X', '== N'}}"
+
+# --- Per-AC oracles (OPTIONAL map — card-schema.md § ac_verification) ---
+# One entry per AC: an EXECUTABLE command verified to exist (npm script / toolchain command /
+# existing test file) — never invented — or an explicit "manual: <what a human checks>".
+# /new Phase 2.5 EXECUTES non-manual oracles; exit status is the primary AC evidence.
+ac_verification:
+  AC-1: "{{command verified to exist, e.g. npm run test -- --grep '{{feature}}'}}"
+  AC-2: "manual: {{what a human checks}}"
     note: "{{what this verifies — maps to AC-N}}"
 
 definition_of_done:

package/framework/.claude/skills/prd/references/audit-phase.md

@@ -165,7 +165,7 @@ INVEST criteria violations:
 - Valuable: card does not deliver user-visible or system-critical value
 - Estimable: scope unclear, cannot estimate effort
 - Small: card too large for one dev session
-- Testable: acceptance criteria not binary pass/fail
+- Testable: acceptance criteria not binary pass/fail (the EARS grammar in card-schema.md § "Acceptance-criteria grammar" is the norm — a clause outside the 5 EARS patterns is a finding)
 
 Requirements smell detection:
 - Ambiguous pronouns without clear antecedent
@@ -199,7 +199,7 @@ Card structure:
   files_likely_touched — flag any unowned consumer (the "hidden-still-shown-in-the-other-mode" class).
 - areas field incomplete
 - git_strategy set to TBD
-- acceptance_criteria not binary testable
+- acceptance_criteria not EARS-conformant (5 patterns, card-schema.md) or not binary testable
 - definition_of_done missing items
 - existing_patterns with stale line_range or missing anchor_text
 - validation_commands missing for cards with testable outputs
@@ -337,48 +337,42 @@ Present the consolidated report to the user.
 
 Use `SendMessage` with `type: "shutdown_request"` to shut down all teammates, then `TeamDelete`.
 
-## Step 6.9 — Apply Findings to Cards
-
-**Goal**: Transform each card from "audited" to "implementation-ready" by editing YAML fields directly.
-
-**Read findings from the persisted report file** (path stored in the session tracker as `$REPORT_FILE`; pattern: `/tmp/check-audit-report-<CARD-ID-SLUG>-<SESSION-ID>.md`).
-
-### Field mapping rules
-
-| Target tag | Card field | Action |
-|---|---|---|
-| `[Target: requirements]` | `requirements` | Append missing requirement or rewrite existing one |
-| `[Target: acceptance_criteria]` | `acceptance_criteria` | Append new `"[ ] [AC-N] ..."` item or rewrite vague AC |
-| `[Target: definition_of_done]` | `definition_of_done` | Append new `"[ ] ..."` item |
-| `[Target: files_likely_touched]` | `files_likely_touched` | Append missing path (no duplicates) |
-| `[Target: depends_on]` | `depends_on` | Append missing card ID |
-| `[Target: areas]` | `areas` | Add missing area key/value |
-| `[Target: git_strategy]` | `git_strategy` | Replace `TBD` with `feat/<CARD-ID>-<slug> from ${git.trunk_branch}` |
-| `[Target: unknowns]` | `unknowns` | Append new `[U-N] UNKNOWN: ...` entry |
-| `[Target: existing_patterns]` | `existing_patterns` | Append missing pattern reference or fix stale line_range/anchor_text |
-| `[Target: validation_commands]` | `validation_commands` | Append missing verification command |
-| `[Target: anti_patterns]` | `anti_patterns` | Append missing DO NOT constraint |
-| `[Target: scope_boundaries]` | `scope_boundaries` | Add missing in_scope or out_of_scope item |
-| `[Target: input_output_examples]` | `input_output_examples` | Append missing scenario or fix incorrect example |
-| `[Target: error_handling]` | `error_handling` | Append missing failure mode or fix incorrect action |
-| `[Target: reuse_analysis]` | `reuse_analysis` | Add missing reuse opportunity or correct file path |
-| `[Target: notes]` | `notes` | Audit trail only (Step 6.9c) |
-
-### Severity policy
-
-- **HIGH**: MUST apply. Card cannot be safely implemented without these.
-- **MEDIUM**: SHOULD apply. Skip only if human judgment needed (mark `[MANUAL]`).
-- **LOW**: Do NOT edit structured fields. Audit trail note only.
-
-### Audit trail in `notes`
-
-After applying all edits, append to `notes`:
-
-```yaml
-## Applied by quality audit — YYYY-MM-DD
-Applied N findings to structured fields (H high, M medium).
-Manual review needed: [list [MANUAL] items, or "none"].
-```
+## Step 6.9 — Apply Findings to Cards (DELEGATED — the orchestrator does not edit YAML)
+
+**Goal**: transform each card from "audited" to "implementation-ready". The mechanical apply
+is DELEGATED to `prd-card-writer` in **MODE: apply-findings** — its § "MODE: apply-findings"
+is the SSOT for the field mapping, severity policy, audit trail, self-validation and stamp
+execution; do NOT restate or re-execute them here. (Measured driver: the inline apply ran
+~48 Edits at full context window — the mechanical phases were 48% of a real run's cost.)
+
+1. Capture the three run-level stamp values ONCE (snippet in § "Holistic-audit provenance
+   stamp" below) and read `$REPORT_FILE` **as a path only** from the session tracker
+   (pattern: `/tmp/check-audit-report-<CARD-ID-SLUG>-<SESSION-ID>.md`) — do not load it.
+2. Spawn ONE `prd-card-writer` subagent — Claude: Task tool, `subagent_type: prd-card-writer`,
+   `model: sonnet` override, `mode: "bypassPermissions"`; Codex: spawn by name from
+   `.codex/agents/` (inherits the session model). THIN prompt, paths only:
+
+   ```
+   MODE: apply-findings
+   REPORT_FILE: <path>
+   CARD_PATHS: <newline-separated card paths>
+   AUDITED_AT: <ts>   AUDITED_COMMIT: <sha-or-empty>   AUDITED_SET: <ID1,ID2,...>
+   VALIDATOR: .framework/framework/scripts/validate-card-baseline.js
+   STAMPER: .framework/framework/scripts/stamp-holistic-audit.js
+   ```
+   (Resolve the two script paths for this install — same base as the validation-phase 0-i
+   gate.)
+3. Consume the COMPACT return (`APPLY-FINDINGS DONE` block):
+   - any card `validator: FAIL` → HALT and surface the validator output verbatim;
+   - route each `[MANUAL]` item to `AskUserQuestion` (they legally survive to
+     validation-phase Step 7 item 1);
+   - **drift guard (zero-cost)**: run `git diff --stat -- "${paths.backlog_dir}"` — the
+     touched files MUST be ⊆ CARD_PATHS; anything else → HALT (the applier edited outside
+     its mandate). Never re-read the card bodies to "double-check" — the validator already
+     did.
+4. **Fallback (delegate-or-else-inline, visible never silent)**: if the spawn is impossible
+   in this install, apply inline following the agent's § "MODE: apply-findings" and log
+   "apply-findings: INLINE FALLBACK (<reason>)" in the audit log.
 
 ### Holistic-audit provenance stamp (since v4.3.0) — consumed by `/new` Step 3d
 
@@ -420,13 +414,10 @@ Hand-edit the YAML only when the script is genuinely unreachable in this install
 
 ### Per-card workflow
 
-For each card:
-1. Read persisted report → collect all findings for this card ID.
-2. Read current card YAML.
-3. Apply HIGH findings first, then MEDIUM, then write audit trail.
-4. Write the `metadata.holistic_audit` provenance block (see "Holistic-audit provenance stamp" above) — **by EXECUTING `stamp-holistic-audit.js` once for the whole card set** (after the last card's field edits), not by hand-editing YAML. **MANDATORY when the audit ran** (see the Fail-safe contract above) — this is what lets `/new`/`new2` skip the per-card plan-auditor when the card is implemented right after `/prd`; `validation-phase.md` Step 7 item 5b deterministically backstops it, but do not rely on the backstop.
-5. Write updated card YAML.
-6. Re-read to verify edits landed correctly.
+The per-card loop (read findings → edit targeted fields → audit trail → validate → stamp)
+is OWNED by `prd-card-writer` § "MODE: apply-findings" (Step 6.9). The stamper runs ONCE for
+the whole card set inside the applier; `validation-phase.md` Step 7 item 5b remains the
+deterministic backstop.
 
 **Note**: No separate commit here — the validation-phase.md Step 7 handles committing all PRD artifacts together.
 

package/framework/.claude/skills/prd/references/validation-phase.md

@@ -21,6 +21,7 @@ Mark task 5 as `in_progress`.
    - **`review_profile` enum + epic `skip`** — `skip|light|balanced|deep`; missing/empty = blocker (the card-writer must compute it via `prd-card-writer.md § Rule C`); epics MUST be `skip`;
    - **conditional `requirements` presence (PO1)** — a child/standalone card with non-empty `acceptance_criteria` + `scope` MUST carry `requirements` (a fresh `/prd` card without them shifts a measured ~3–4M-token back-fill into `/new`'s orchestrator — see `card-schema.md` § "Authoring completeness invariants");
    - **unresolved `[NEEDS CLARIFICATION: …]` markers** — a card carrying a planning ambiguity is NOT implementable. Resolve each marker (with the user via `AskUserQuestion` when it needs a human answer, or from Discovery/PRD material when it does not), edit the card, re-run;
+   - **EARS grammar on child/standalone AC** (5 patterns + vague-verb ban-list — `card-schema.md` § "Acceptance-criteria grammar") = BLOCKER; `ac_verification` coverage = WARN-only;
    - the universal field-state matrix + remaining enums (`card-schema.md`).
 
    **Why executed and not recited:** the prose version of this gate has already failed silently on a real run (a whole card family shipped with zero audit trail). A recited check degrades under context pressure; an executed one cannot.
@@ -77,7 +78,7 @@ Mark task 5 as `in_progress`.
    Then execute the audit protocol described within, using the card IDs from Step 5.
    The protocol auto-detects which agents to include (security and performance
    are signal-triggered, no manual profile selection needed).
-   **I/O contract:** `audit-phase.md` may edit card YAML files (e.g. its Step 6.9 normalisation pass). The list of all card paths modified by the audit (including those edited in Step 6.9) is the complete set that Step 7 item 6 must stage. The glob `FEAT-XXXX-*.yml (all cards from Step 5)` in item 6 covers this; note it explicitly so that context compaction does not cause a model to stage only the pre-audit originals.
+   **I/O contract:** `audit-phase.md` may edit card YAML files (its Step 6.9 apply runs via the `prd-card-writer` MODE: apply-findings subagent). The list of all card paths modified by the audit (including those edited in Step 6.9) is the complete set that Step 7 item 6 must stage. The glob `FEAT-XXXX-*.yml (all cards from Step 5)` in item 6 covers this; note it explicitly so that context compaction does not cause a model to stage only the pre-audit originals.
 3. Wait for audit report and card edits.
 
 **Gate:** all HIGH/MEDIUM findings resolved, no open `[MANUAL]` items that require external human input beyond this orchestrator. (Items that the orchestrator can resolve autonomously are resolved before this gate; items that need a human decision were already routed to `AskUserQuestion` inside `audit-phase.md`. Items that survive to Step 7 item 1 are those that received a human answer but required card re-edits — these are explicitly handled there.)

package/framework/agents/card-schema.md

@@ -56,7 +56,8 @@ Legend: **R** = required, present **and non-empty** · **E** = required key, val
 | `scope` | R | R | R | **never omittable** — encodes intent |
 | `scope_boundaries` | R | C | C | "Omit for standalone cards with no siblings" (`prd-card-writer.md`) |
 | `requirements` | C | R | R | EPIC tracks via AC-EPIC; CHILD/STANDALONE: faithfully derivable from AC+scope when both present — see consumer contract |
-| `acceptance_criteria` | R (AC-EPIC) | R | R | |
+| `acceptance_criteria` | R (AC-EPIC) | R | R | CHILD/STANDALONE: EARS grammar — see § "Acceptance-criteria grammar (EARS)" |
+| `ac_verification` | — | C | C | OPTIONAL map `AC-N → executable oracle` (or `manual: <check>`); authored by `/prd`, executed by `/new` Phase 2.5 — see § below |
 | `definition_of_done` | R | R | R | |
 | `depends_on` / `blocks` | E (`[]`) | E | E | |
 | `estimated_complexity` | C | R | R | |
@@ -212,6 +213,64 @@ Rules:
 - Omit any sub-field whose session id is unavailable (env var unset) rather than writing a
   placeholder.
 
+## Acceptance-criteria grammar (EARS) + per-AC oracles (since the EARS+verify wave)
+
+**Why**: a prose AC passes gates without being verifiable ("handle it correctly"), and
+prose gates get gamed (measured: visible/holdout gap +28pt per 10x code; exploit rate
+0.6→13.9% post-RL). Two complementary halves: the AC is binary BY FORM (EARS), and its
+verification is EXECUTABLE, defined at planning time.
+
+### EARS grammar (CHILD/STANDALONE `acceptance_criteria` — epic AC-EPIC roll-ups exempt)
+
+Every AC entry is `"[ ] [AC-N] <EARS clause>"` where the clause matches ONE of the five
+EARS patterns:
+
+| Pattern | Form |
+|---|---|
+| Ubiquitous | `THE SYSTEM SHALL <behavior>` |
+| Event-driven | `WHEN <trigger> THE SYSTEM SHALL <behavior>` |
+| State-driven | `WHILE <state> THE SYSTEM SHALL <behavior>` |
+| Optional-feature | `WHERE <feature is present> THE SYSTEM SHALL <behavior>` |
+| Unwanted-behavior | `IF <error condition> THEN THE SYSTEM SHALL <behavior>` |
+
+Non-regression variant: `… THE SYSTEM SHALL CONTINUE TO <existing behavior>`.
+
+- The clause body stays in the project language (`identity.language`); the EARS keywords
+  stay English — they are syntactic markers, like field names.
+- **Vague verbs are BANNED** (validator ban-list: `correttamente`, `appropriato/a`,
+  `properly`, `appropriately`, `as expected`, `gracefully`, `handle correctly`, `gestire
+  corrett*`) — name the observable behavior instead.
+- Enforced by `validate-card-baseline.js --prd` (BLOCKER) — i.e. at `/prd` authoring time
+  only. Legacy cards are never retro-blocked: `/new`'s baseline conformance (1b-iii) does
+  NOT apply the EARS check.
+
+Worked example (rewritten from a real card):
+- Before: `"[ ] [AC-2] La lista fornitori si aggiorna correttamente dopo il salvataggio"`
+- After: `"[ ] [AC-2] WHEN il salvataggio di un fornitore va a buon fine THE SYSTEM SHALL mostrare il fornitore aggiornato nella lista senza reload manuale"`
+
+### `ac_verification` — per-AC executable oracle (OPTIONAL map)
+
+```yaml
+ac_verification:
+  AC-1: "npm run test -- --grep 'supplier hub layout'"
+  AC-2: "grep -q 'useSupplierList' src/app/settings/suppliers/page.tsx"
+  AC-3: "manual: verifica visiva dello stato empty su viewport 375px"
+```
+
+- **Authoring** (`prd-card-writer`): a command is written ONLY if verified to exist — an
+  npm script in `package.json`, a command in `toolchain.commands.*`, a cited test file
+  that exists. NEVER invent commands (same class as the Field Grounding Rule). Not
+  automatable → explicit `manual: <what a human checks>`.
+- **Consumption** (`/new` Phase 2.5 completeness check — the AC-verification owner): an AC
+  with a non-`manual:` oracle is verified by EXECUTING it; the exit status is the primary
+  evidence. Judgment covers only `manual:` oracles and oracle-less ACs. (`qa-sentinel` is
+  deliberately NOT the consumer — AC verification is out of its scope by contract.)
+- **Relation to `validation_commands`**: that field stays the card-level suite;
+  `ac_verification` is the per-AC mapping. The validator WARNs when a non-manual oracle
+  is absent from `validation_commands` (drift guard between the two).
+- **Enforcement is WARN-first** (the `--prd` validator warns on missing entries for cards
+  with code-testable outputs); any hard gate comes only after telemetry on real runs.
+
 ## Writer contract
 
 The canonical writer is the `prd-card-writer` agent. It emits the full baseline for the

package/framework/docs/ROOT-PRIMITIVES.md

@@ -44,6 +44,7 @@ key was introduced:
 | Commands table | `toolchain.commands.*` → `package.json` scripts (rows with no source are omitted) |
 | Repo map | non-empty `paths.*` + a derived source root |
 | `git.trunk_branch` | `git.trunk_branch` |
+| `git.protected_branch` | `git.protected_branch` → `git.trunk_branch` (default) — the "never push directly" branch; differs from the trunk only in a two-branch gitflow |
 | feature gates | `features.has_backlog` / `has_adrs` / `has_i18n` / `has_design_system` |
 
 ## Overlay

package/framework/scripts/validate-card-baseline.js

@@ -29,7 +29,11 @@
  *     acceptance_criteria + scope MUST have non-empty requirements;
  *   - epic `review_profile` must be `skip`;
  *   - `[NEEDS CLARIFICATION: …]` ambiguity markers in the raw YAML are BLOCKERS —
- *     a card ships only when every planning ambiguity has been resolved.
+ *     a card ships only when every planning ambiguity has been resolved;
+ *   - EARS grammar on child/standalone acceptance_criteria (5 patterns + vague-verb
+ *     ban-list) — BLOCKER; epics exempt. SSOT: card-schema.md § "Acceptance-criteria
+ *     grammar (EARS)";
+ *   - `ac_verification` per-AC oracle coverage — WARN-only (never fails the run).
  *
  * Module API (for CI self-tests in scripts/check-card-baseline.js):
  *   const { validateCard, detectProfile, loadSchema, loadEnums } = require(...)
@@ -373,12 +377,30 @@ function scanAmbiguityMarkers(text) {
   return out;
 }
 
+// EARS grammar — SSOT: card-schema.md § "Acceptance-criteria grammar (EARS)".
+// Keywords are English syntactic markers; the clause body may be any language.
+const EARS_PATTERNS = [
+  /^THE SYSTEM SHALL .+/,
+  /^WHEN .+ THE SYSTEM SHALL .+/,
+  /^WHILE .+ THE SYSTEM SHALL .+/,
+  /^WHERE .+ THE SYSTEM SHALL .+/,
+  /^IF .+ THEN THE SYSTEM SHALL .+/,
+];
+const VAGUE_VERB_RE = /(correttamente|appropriat[oa]|properly|appropriately|as expected|gracefully|handle correctly|gestire corrett)/i;
+
+/** "[ ] [AC-3] WHEN … THE SYSTEM SHALL …" → { id: 'AC-3', clause: 'WHEN … …' } (null if unparseable) */
+function parseAcEntry(entry) {
+  const m = String(entry).match(/^\s*\[[ xX]?\]\s*\[(AC-\d+)\]\s*(.+)$/);
+  return m ? { id: m[1], clause: m[2].trim() } : null;
+}
+
 /**
  * The deterministic subset of /prd validation-phase Step 6 item 0 (see file header).
- * Returns string[] errors. `text` is the raw YAML (marker scan), `card` the parsed map.
+ * Returns { errors, warnings }. `text` is the raw YAML (marker scan), `card` the parsed map.
  */
 function prdGateChecks(card, text, profile) {
   const errors = [];
+  const warnings = [];
   if (profile !== 'EPIC' && nonEmpty(card.acceptance_criteria) && nonEmpty(card.scope) && !nonEmpty(card.requirements)) {
     errors.push("has acceptance_criteria + scope but no 'requirements' — emit requirements (faithful restatement of AC + scope) before commit (PO1)");
   }
@@ -388,7 +410,37 @@ function prdGateChecks(card, text, profile) {
   for (const m of scanAmbiguityMarkers(text)) {
     errors.push(`unresolved ambiguity marker — resolve with the user before commit: ${m}`);
   }
-  return errors;
+  // EARS grammar + vague-verb ban (child/standalone only; epic AC-EPIC roll-ups exempt)
+  if (profile !== 'EPIC' && Array.isArray(card.acceptance_criteria)) {
+    for (const entry of card.acceptance_criteria) {
+      const ac = parseAcEntry(entry);
+      if (!ac) continue; // malformed entry shape is the matrix/consumer contract's concern
+      if (VAGUE_VERB_RE.test(ac.clause)) {
+        errors.push(`${ac.id} uses a banned vague verb — name the observable behavior (card-schema.md § EARS): "${ac.clause.slice(0, 90)}"`);
+      } else if (!EARS_PATTERNS.some((re) => re.test(ac.clause))) {
+        errors.push(`${ac.id} is not an EARS clause (THE SYSTEM SHALL / WHEN|WHILE|WHERE … THE SYSTEM SHALL / IF … THEN THE SYSTEM SHALL): "${ac.clause.slice(0, 90)}"`);
+      }
+    }
+    // ac_verification coverage — WARN-only (enforcement is data-driven, never a blocker here)
+    const av = card.ac_verification;
+    const hasCodeOutputs = nonEmpty(card.files_likely_touched);
+    if (!nonEmpty(av)) {
+      if (hasCodeOutputs) warnings.push("no 'ac_verification' map — consider per-AC executable oracles (or 'manual: …') per card-schema.md § ac_verification");
+    } else if (typeof av === 'object' && !Array.isArray(av)) {
+      const vcText = JSON.stringify(card.validation_commands || []);
+      for (const entry of card.acceptance_criteria) {
+        const ac = parseAcEntry(entry);
+        if (!ac) continue;
+        const oracle = av[ac.id];
+        if (oracle == null || String(oracle).trim() === '') {
+          warnings.push(`ac_verification has no entry for ${ac.id}`);
+        } else if (!/^manual:/i.test(String(oracle)) && !vcText.includes(String(oracle).slice(0, 40))) {
+          warnings.push(`${ac.id} oracle is not in validation_commands (drift guard): "${String(oracle).slice(0, 60)}"`);
+        }
+      }
+    }
+  }
+  return { errors, warnings };
 }
 
 // --- CLI --------------------------------------------------------------------
@@ -420,7 +472,12 @@ function main(argv) {
       continue;
     }
     const { profile, errors } = validateCard(card, { matrix, enums, filename: path.basename(file) });
-    if (prdMode) errors.push(...prdGateChecks(card, text, profile));
+    let warnings = [];
+    if (prdMode) {
+      const g = prdGateChecks(card, text, profile);
+      errors.push(...g.errors);
+      warnings = g.warnings;
+    }
     if (errors.length) {
       failed++;
       process.stdout.write(`✖ ${file} [${profile}] — ${errors.length} issue(s):\n`);
@@ -428,6 +485,7 @@ function main(argv) {
     } else {
       process.stdout.write(`✓ ${file} [${profile}]\n`);
     }
+    for (const w of warnings) process.stdout.write(`    ⚠ ${w}\n`);
   }
   return failed ? 1 : 0;
 }

package/framework/templates/baldart.config.template.yml

@@ -416,6 +416,15 @@ git:
   # (falling back to asking the user). Default kept as "develop" for back-compat.
   trunk_branch: develop
 
+  # Protected branch — the branch that MUST NOT receive direct pushes (the
+  # production/release line). Skills resolve this key for the "never push
+  # directly to X" rule. DEFAULTS to `trunk_branch` when omitted, so single-trunk
+  # repos need not set it. Set it explicitly ONLY for a two-branch gitflow where
+  # the protected line differs from the integration trunk — e.g.
+  # `protected_branch: main` while `trunk_branch: develop` (features integrate
+  # into develop; main is reached only via a release/hotfix PR).
+  protected_branch: develop
+
   # How `/mw` lands the feature branch onto the trunk:
   #
   #   pr          (default) — push feature branch, open a PR via `gh pr create`,

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

@@ -4,6 +4,19 @@ 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.5.0 — 2026-07-02
+
+- **Protected branch decoupled from the integration trunk**: the "NEVER push directly"
+  MUST now resolves the new `{{ git.protected_branch }}` slot instead of
+  `{{ git.trunk_branch }}`, and explicitly permits direct pushes to other branches
+  (including the integration trunk when it differs) when the owner authorizes it.
+  `git.protected_branch` defaults to `git.trunk_branch`, so single-trunk repos are
+  byte-unchanged; a two-branch gitflow sets it (e.g. `protected_branch: main` while
+  `trunk_branch: develop` stays the worktree base + PR target). Fixes the case where a
+  consumer with `trunk_branch: develop` had its agents refuse a direct `develop` push
+  even though `develop` was the integration branch and `main` was the protected line.
+  Cross-tool: pure slot resolution in the shared skeleton — portable (Claude + Codex).
+
 ## 1.4.0 — 2026-07-02
 
 - **Analysis-profile vocabulary on the understand-before-implement MUST**: the

package/framework/templates/primitives/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- baldart-primitive: name=AGENTS primitive_version=1.4.0
+<!-- baldart-primitive: name=AGENTS primitive_version=1.5.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,
@@ -55,7 +55,9 @@ mechanics — this file remains the single source of truth for the protocol.
 - MUST use commit format `{{ git.commit_format }}`; small, traceable commits.
 - MUST NOT commit with failing lint/type checks. Full build only before opening a PR.
 - MUST pre-sync (`git fetch`, clean status, confirm branch, `--ff-only`) and NEVER push
-  directly to `{{ git.trunk_branch }}` — all changes reach it via PR.
+  directly to `{{ git.protected_branch }}` — the protected branch reaches its state only
+  via PR. Other branches (including the integration branch `{{ git.trunk_branch }}` when it
+  differs) MAY be pushed to directly when the owner authorizes it.
 - MUST get owner approval before force-push/reset or deleting an UNMERGED branch (create a
   `backup/<YYYYMMDD>-<reason>` tag first). Deleting an already-merged branch is routine.
 - MUST NOT hardcode secrets / tokens / API keys (env vars only), expose internal stack

package/package.json

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

package/src/commands/configure.js

@@ -102,6 +102,38 @@ function detectTrunkBranch(cwd = process.cwd()) {
   }
 }
 
+/**
+ * Autodetect the protected branch (git.protected_branch) — the branch that MUST
+ * NOT receive direct pushes (production/release line). In a two-branch gitflow
+ * this differs from the integration `trunk_branch`: features integrate into the
+ * trunk (worktree base + PR target), while a separate protected branch is only
+ * reached via release/hotfix PRs.
+ * Heuristic: if trunk is NOT already `main`/`master` and such a branch exists,
+ * that's the protected line; otherwise the protected branch IS the trunk
+ * (single-trunk repo — the back-compat default, since protected_branch defaults
+ * to trunk_branch when absent).
+ */
+function detectProtectedBranch(cwd = process.cwd(), trunk = 'develop') {
+  try {
+    const { execSync } = require('child_process');
+    const opts = { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000, encoding: 'utf8' };
+    const branches = (() => {
+      try { return execSync('git branch --format=%(refname:short)', opts).split('\n').map((s) => s.trim()); }
+      catch (_) { return []; }
+    })();
+    if (trunk !== 'main' && trunk !== 'master') {
+      for (const cand of ['main', 'master']) {
+        if (branches.includes(cand)) {
+          return { value: cand, reason: `two-branch gitflow: '${cand}' is the protected line (trunk is '${trunk}').` };
+        }
+      }
+    }
+    return { value: trunk, reason: `single-trunk repo — protected branch is the trunk ('${trunk}').` };
+  } catch (_) {
+    return { value: trunk, reason: `probe failed — protected branch defaults to trunk ('${trunk}').` };
+  }
+}
+
 /**
  * Autodetect whether this project develops in parallel git worktrees
  * (`git worktree list` shows linked worktrees beyond the main one). Used to
@@ -371,6 +403,7 @@ function detect(cwd = process.cwd()) {
     : '';
 
   const trunkBranchProbe = detectTrunkBranch(cwd);
+  const protectedBranchProbe = detectProtectedBranch(cwd, trunkBranchProbe.value);
   const mergeStrategyProbe = detectMergeStrategy(cwd, trunkBranchProbe.value);
   // Default schema_deploy_from_trunk_only ON when parallel worktrees are in use
   // (the topology prone to migration-history desync). Otherwise keep the
@@ -532,6 +565,7 @@ function detect(cwd = process.cwd()) {
       // Set to plain strings — the structured probe details (`protected`,
       // `reason`) are kept on a sibling key so mergePreserving stays type-safe.
       trunk_branch: trunkBranchProbe.value,
+      protected_branch: protectedBranchProbe.value,
       merge_strategy: mergeStrategyProbe.value,
     },
     _probes: {
@@ -539,6 +573,7 @@ function detect(cwd = process.cwd()) {
       // interactivePrompts to surface the autodetection reasoning.
       merge_strategy: mergeStrategyProbe,
       trunk_branch: trunkBranchProbe,
+      protected_branch: protectedBranchProbe,
     },
   };
 

package/src/commands/update.js

@@ -1551,6 +1551,12 @@ async function update(options = {}, unknownArgs = []) {
                     + 'Until it is set, those skills autodetect the trunk (origin/HEAD → develop/main/master) '
                     + 'and warn on each run; run `npx baldart configure` to persist it and make it deterministic.');
                 }
+                if (allMissing.includes('git.protected_branch')) {
+                  UI.warning('`git.protected_branch` is the branch the "never push directly" rule protects '
+                    + '(AGENTS.md). It DEFAULTS to `git.trunk_branch`, so single-trunk repos are unchanged; '
+                    + 'set it (e.g. `main`) only for a two-branch gitflow where the protected line differs from '
+                    + 'the integration trunk (e.g. trunk `develop`, protected `main`).');
+                }
               }
             }
           } catch (_) {

package/src/utils/root-primitives.js

@@ -159,6 +159,11 @@ function resolveSlots(cwd, cfg) {
     'stack.summary': stackSummary,
     'stack.node_suffix': nodeSuffix,
     'git.trunk_branch': git.trunk_branch || 'main',
+    // The branch that MUST NOT receive direct pushes (production/protected).
+    // Defaults to trunk_branch so single-trunk repos are unchanged; two-branch
+    // gitflows set it explicitly (e.g. protected_branch: main while
+    // trunk_branch: develop is the integration/PR target + worktree base).
+    'git.protected_branch': git.protected_branch || git.trunk_branch || 'main',
     'git.feature_prefix': 'feat', // STATIC BALDART convention
     'git.commit_format': '[FEAT-XXXX] description', // STATIC default (override via overlay)
     'i18n.registry': paths.i18n_registry || 'the i18n registry',