feat(git-tools): consume .mosaic/repo.json declarations in compat mode (T51 WP5b, closes #1413)

Spec of record: docs/plans/2026-08-23_repo-structure-declaration.md
(brain repo) sections 4 (consumption contract), 5.1/5.3/5.4, 1.2a.

New shared lib repo-decl.sh: one consumption surface for the wrappers.
Loads .mosaic/repo.json, classifies absent/invalid/valid via the WP1
validator (5.1: ALL consumers invoke the same script; 5.4 point 1:
invalid = ABSENT + loud error naming file/key/reason), extracts the
consumed fields, normalizes origin for 5.3 comparisons, validates
transitions per 4.2 (a CLI flag is input, not authority), and resolves
host:/ paths FAIL-CLOSED while MOSAIC_HOST_ROOT is unset (1.2a — no
WP5b consumer resolves a path today; the helper exists so the first
that needs one cannot guess). v1 declarations validate but carry no
consumable fields: legacy behavior with a note.

pr-create.sh: base precedence -B (validated as an allowed transition)
-> declared integration_trunk -> legacy WP5a forge-default floor
(unmanaged/absent/v1 per 4.3 reversible class, warn + legacy). Remote
mismatch vs canonical_remote refuses (write path, 5.3).

pr-merge.sh: transition validation per declared flow; the hardcoded
main/next target check survives only for undeclared repos during the
rollout window (4.3 irreversible class, loud warning). Remote mismatch
refuses.

ci-queue-wait.sh: ROUTE CONTEXT only (4.1, C4/jarvis F8/DR2 R9) —
branch-selection semantics untouched, absence silent, invalid reported
per 5.4.

mosaic-worktree.sh: staged rule 4.4 — invalid declaration fails
branch-creation loud, absent warns and proceeds, valid contributes
policy ADVICE only (4.5: placement stays derived; the advisory
worktree_root comparison runs only when MOSAIC_HOST_ROOT is set, per
1.2a warn-and-omit). Consuming via a self-located source line and
set -u-safe env access.

mutate-push-guard.sh: NO change — spec 4.1 names it for push-to-trunk
protection, but the tool as shipped is a mutation-coverage meta-tool
for push-guard.sh with no trunk-protection logic to consult; the
disposition is documented in #1413 rather than force-feeding a fake
consumption.

All wrappers degrade SILENTLY to legacy behavior when repo-decl.sh is
absent from a copied tool subset (a legal deployment shape; a note
there broke single-line diagnostic contracts in
test-pr-merge-message-field).

test-repo-decl-consumption.sh: 67 assertions, green x2, hermetic; runs
RED against pre-change tools via WP5B_TOOLS (49 red there — red-first
evidence). Covers every 5.4 hostile-input class applicable to consumed
fields (missing, malformed, unknown schema_version, v1, unknown key,
bad refs, cross-field, userinfo URL, remote mismatch) plus transition
validation, base precedence, absence policies, staged worktree rule,
route context, and 1.2a fail-closed. Enumerated on the S1 surface
(enumeration guard green: population 71, enumerated 57).

Neighbor suites green: WP5a fallback suite, all six pr-merge suites,
worktree large-repo, help/login/interactive suites. S1 chain failures
(fleet-units systemd bus, invariant_r host Pi version, pr-edit
credential-helper env) reproduce identically at origin/next —
environmental, untouched by this diff. No TS/vitest lane touched
(shell tools only).

packages/mosaic/framework/tools/git/pr-create.sh

@@ -78,8 +78,8 @@ gitea_pr_create_api() {
     # historical "main" literal, which mistargeted every fallback PR on
     # repos whose trunk is not main (e.g. mosaicstack/stack -> next).
     local api_base=""
-    if [[ -n "$BASE_BRANCH" ]]; then
-        api_base="$BASE_BRANCH"
+    if [[ -n "$EFFECTIVE_BASE" ]]; then
+        api_base="$EFFECTIVE_BASE"
     else
         api_base=$(gitea_default_branch) || {
             echo "Error: could not resolve the forge default branch for the API-fallback base; pass -B <branch> explicitly" >&2
@@ -198,6 +198,52 @@ if [[ -z "$HEAD_BRANCH" ]]; then
     HEAD_BRANCH=$(git branch --show-current)
 fi
 
+# T51 WP5b: declaration-driven base resolution (spec 4.1). Precedence:
+#   explicit -B  -> validated as an ALLOWED transition (4.2: a flag is input,
+#                    not authority) when a consumable declaration exists
+#   declared trunk (v2 declarations only) -> used directly
+#   legacy        -> WP5a forge-default floor (unmanaged/absent/v1, 4.3)
+# shellcheck source=packages/mosaic/framework/tools/git/repo-decl.sh
+if [ -f "$SCRIPT_DIR/repo-decl.sh" ]; then
+    source "$SCRIPT_DIR/repo-decl.sh"
+    repo_decl_load
+else
+    DECL_STATE=absent; DECL_SCHEMA=""
+    repo_decl_warn() { printf 'repo-decl: %s\n' "$*" >&2; }
+    repo_decl_report_invalid() { :; }
+    repo_decl_warn_absent_reversible() { :; }
+    repo_decl_warn_absent_irreversible() { :; }
+    repo_decl_remote_matches() { return 0; }
+    repo_decl_check_transition() { return 2; }
+fi
+EFFECTIVE_BASE="$BASE_BRANCH"
+case "$DECL_STATE" in
+    invalid) repo_decl_report_invalid ;;
+esac
+if [[ "$DECL_STATE" == valid && "$DECL_SCHEMA" != 2 ]]; then
+    repo_decl_warn "declaration is v$DECL_SCHEMA — carries no consumable flow/trunk fields; legacy behavior"
+fi
+if [[ "$DECL_STATE" == valid && "$DECL_SCHEMA" == 2 ]]; then
+    # Write path: a normalized-remote mismatch refuses (spec 5.3).
+    if ! repo_decl_remote_matches; then
+        echo "Error: origin remote does not match the declared canonical_remote (spec 5.3, write path) — refusing to create a PR against the wrong forge. Fix the origin remote or the declaration." >&2
+        exit 1
+    fi
+    if [[ -n "$BASE_BRANCH" ]]; then
+        trc=0
+        repo_decl_check_transition "$HEAD_BRANCH" "$BASE_BRANCH" || trc=$?
+        if [[ "$trc" == 1 ]]; then
+            echo "Error: -B '$BASE_BRANCH' is not an allowed transition for head '$HEAD_BRANCH' under the declared flow (spec 4.2). The declaration governs; supply an allowed base." >&2
+            exit 1
+        fi
+        # trc 2 cannot happen here (state=valid): 0 = allowed
+    else
+        EFFECTIVE_BASE="$DECL_TRUNK"
+    fi
+elif [[ -z "$BASE_BRANCH" ]]; then
+    repo_decl_warn_absent_reversible "pr-create"
+fi
+
 # Add issue reference to body if provided
 if [[ -n "$ISSUE" ]]; then
     if [[ -n "$BODY" ]]; then
@@ -215,7 +261,7 @@ case "$PLATFORM" in
     github)
         CMD=(gh pr create --title "$TITLE")
         [[ -n "$BODY" ]] && CMD+=(--body "$BODY")
-        [[ -n "$BASE_BRANCH" ]] && CMD+=(--base "$BASE_BRANCH")
+        [[ -n "$EFFECTIVE_BASE" ]] && CMD+=(--base "$EFFECTIVE_BASE")
         [[ -n "$HEAD_BRANCH" ]] && CMD+=(--head "$HEAD_BRANCH")
         [[ -n "$LABELS" ]] && CMD+=(--label "$LABELS")
         [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
@@ -240,7 +286,7 @@ case "$PLATFORM" in
         REPO_ARGS=(--repo "$REPO_SLUG" --login "$GITEA_LOGIN_NAME")
         CMD=(tea pr create "${REPO_ARGS[@]}" --title "$TITLE")
         [[ -n "$BODY" ]] && CMD+=(--description "$BODY")
-        [[ -n "$BASE_BRANCH" ]] && CMD+=(--base "$BASE_BRANCH")
+        [[ -n "$EFFECTIVE_BASE" ]] && CMD+=(--base "$EFFECTIVE_BASE")
         [[ -n "$HEAD_BRANCH" ]] && CMD+=(--head "$HEAD_BRANCH")
 
         # Handle labels for tea