baldart 4.95.0 → 4.96.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.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).**

package/VERSION

@@ -1 +1 @@
-4.95.0
+4.96.0

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/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.95.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',