@soleur/opencode 0.0.0-stage → 1.0.0

package/scripts/render-c4-model.sh

@@ -0,0 +1,217 @@
+#!/usr/bin/env bash
+# render-c4-model.sh — Render the compiled LikeC4 model artifact from a repo's .c4 sources.
+#
+# Usage: bash <plugin>/scripts/render-c4-model.sh [--root DIR] [--out PATH] [--help]
+#
+# Compiles every LikeC4 DSL source (*.c4) under <root>/knowledge-base/engineering/
+# architecture/diagrams/ into the layouted model.likec4.json that the web Knowledge
+# Base viewer renders at runtime (the browser ships @likec4/diagram WITHOUT the
+# compiler, so the JSON must be precompiled and committed).
+#
+# PLUGIN-OWNED (ADR-235 amendment, #8542 follow-up). It lived at the Soleur repo's
+# scripts/regenerate-c4-model.sh, which a self-hosted install does not have, so the
+# merge resolver could never regenerate in a customer repo. That path is now a thin
+# wrapper for this repo's own callers; this file is the one renderer.
+#
+# --root DIR  The repository whose diagrams to render. Default: the git top level of
+#             the current directory. The CODE comes from beside this script; only the
+#             DATA comes from --root (ADR-179's code-root / data-root split).
+# --out PATH  Write the validated, canonicalized model to PATH instead of the tracked
+#             artifact. Used by plugins/soleur/test/c4-model-freshness.test.sh to render
+#             to a temp path with identical logic, then byte-diff against the committed
+#             artifact. Default: <root>/.../diagrams/model.likec4.json.
+#
+# Pinned to likec4@1.50.0 — MUST match apps/web-platform/Dockerfile +
+# package.json @likec4/core/@likec4/diagram (guarded by c4-likec4-version-pin.test.ts).
+# A CLI/client version skew silently desyncs the rendered diagram.
+#
+# BUMPING LIKEC4 — the version is half of a pair with LIKEC4_BEFORE. The version pins ONE
+# package; `--before=<date>` resolves its ~190 transitive deps as of that date, so a
+# tarball published minutes ago (which npm's CDN can 404, #9300) is never requested.
+#   1. Pick the new version, then a date that is the day AFTER its publish day and >= 3 days
+#      old (a date-only --before is midnight UTC and EXCLUSIVE: a version published at 17:11Z
+#      on day D is invisible to --before=D and fails with ETARGET; claude-code 2.1.284 is a
+#      live example of that arithmetic, not a likec4 fact):
+#        npm view likec4@<version> time --json
+#   2. Move LIKEC4_VERSION and LIKEC4_BEFORE together in EVERY site in one commit: this
+#      script, plugins/soleur/lib/c4-from-components.ts, the `Install likec4 CLI` steps
+#      in .github/workflows/ci.yml and main-health-monitor.yml, and the `cli-tools` stage
+#      of apps/web-platform/Dockerfile (the date is a literal there). Every one of those
+#      installs must be exactly `npm install -g likec4@<version> --before=<date>
+#      --ignore-scripts` (a Dockerfile one prefixed `RUN `): the tests exercise the binary a
+#      scripts-off install makes, so the shipped one must match. The claude-code install is the
+#      exception (its postinstall places the binary). Sweep with: git grep 'likec4@1\.'
+#      c4-likec4-version-pin.test.ts asserts parity, the age floor, the flag and the exact form.
+#   Deliberately version-only (no --before): package.json (installed by lock-based
+#   `npm ci --ignore-scripts`) and the interactive `validate` recipes in the architecture skill docs,
+#   which also run scripts-on (they are asserted for the version only).
+#   A claude-code bump needs no date (its tree is exact-pinned platform packages with
+#   nothing floating) but claude-cli-pin-knows-models.test.ts must stay green.
+#   Policy: the date moves with a likec4 bump, or sooner if a transitive advisory affects
+#   the CLI; the tree is otherwise frozen on purpose. A version bump that forgets the date
+#   fails the install with ETARGET (the registry knows publish times; the offline guard
+#   does not). A private registry mirror that serves metadata WITHOUT per-version publish
+#   times does not fail: npm silently ignores --before there (measured against
+#   npm-pick-manifest), so the pin is inert on that mirror and the tree floats again.
+#
+# Renders OFF-TREE to a temp path and validates structurally BEFORE publishing:
+# `likec4 export json` exits 0 even on an unresolved-reference / empty model, so
+# an exit-0 check is NOT proof of a good artifact — see learnings
+# 2026-06-05-external-cli-exit-0-is-not-proof-validate-the-artifact.md and
+# apps/web-platform/server/c4-render.ts. Three publish gates below: a clean
+# diagnostic stream, a non-empty object-typed elements map, and a non-empty
+# object-typed views map — so neither a broken .c4 source nor a failed layout
+# can clobber the good committed artifact.
+#
+# WRITES EXACTLY ONE FILE, the output path. The merge resolver commits whatever this
+# changes, and asserts nothing else moved (resolve-regenerable-conflicts.sh, D4).
+#
+# Idempotent: rerunning against unchanged sources produces byte-identical output.
+
+set -euo pipefail
+
+LIKEC4_VERSION="1.50.0"
+LIKEC4_BEFORE="2026-09-28"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CANONICAL_CLI="$SCRIPT_DIR/../lib/c4-canonical-cli.mjs"
+ROOT=""
+OUT=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --help)
+      sed -n '2,/^$/s/^# \{0,1\}//p' "${BASH_SOURCE[0]}"
+      exit 0
+      ;;
+    --root)
+      [[ -n "${2:-}" ]] || { echo "ERROR: --root requires a DIR argument" >&2; exit 2; }
+      ROOT="$2"
+      shift 2
+      ;;
+    --out)
+      [[ -n "${2:-}" ]] || { echo "ERROR: --out requires a PATH argument" >&2; exit 2; }
+      OUT="$2"
+      shift 2
+      ;;
+    *)
+      echo "ERROR: unknown argument: $1 (try --help)" >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [[ -z "$ROOT" ]]; then
+  ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" \
+    || { echo "ERROR: not inside a git work tree and no --root given" >&2; exit 2; }
+fi
+ROOT="$(cd "$ROOT" 2>/dev/null && pwd)" || { echo "ERROR: --root is not a directory" >&2; exit 2; }
+DIAGRAMS_DIR="$ROOT/knowledge-base/engineering/architecture/diagrams"
+[[ -n "$OUT" ]] || OUT="$DIAGRAMS_DIR/model.likec4.json"
+
+if [[ ! -d "$DIAGRAMS_DIR" ]]; then
+  echo "ERROR: diagrams directory not found at $DIAGRAMS_DIR" >&2
+  exit 1
+fi
+
+# Guard: at least one DSL source. NOT "spec.c4 + model.c4 + views.c4": soleur:sync writes
+# generated-components.c4, spec.c4 and views.c4 into a customer repo and never model.c4
+# (that one belongs to soleur:architecture), so the all-three form refused every plainly
+# synced repo. What makes a render trustworthy is the two gates below, not a file list.
+# Every extension likec4 1.50.0 compiles, at any depth — likec4 walks the whole directory.
+if [[ -z "$(find "$DIAGRAMS_DIR" -type f \( -name '*.c4' -o -name '*.likec4' -o -name '*.like-c4' \) -print -quit)" ]]; then
+  echo "ERROR: no .c4 source (*.c4, *.likec4 or *.like-c4) in $DIAGRAMS_DIR" >&2
+  exit 1
+fi
+
+[[ -f "$CANONICAL_CLI" ]] || { echo "ERROR: canonicalizer not found beside this script at $CANONICAL_CLI" >&2; exit 1; }
+
+# A missing tool is a machine problem, not a fault in the .c4 source: name it (rc 2, like a usage error).
+for _tool in jq node npx mktemp; do
+  command -v "$_tool" >/dev/null 2>&1 \
+    || { echo "ERROR: rendering the C4 model needs jq, node and npx on PATH; '$_tool' is missing" >&2; exit 2; }
+done
+
+TMP="$(mktemp -d)"
+PUBLISH_TMP=""
+trap 'rm -rf "$TMP"; [[ -n "$PUBLISH_TMP" ]] && rm -f "$PUBLISH_TMP"' EXIT
+RENDER_LOG="$TMP/render.log"
+
+# Render off-tree with the pinned CLI, capturing all diagnostics. A non-zero
+# exit is a hard failure; but likec4 ALSO exits 0 on broken sources, so the
+# exit code alone is never sufficient (see the three gates below).
+# CI is UNSET for the child and colour forced off: under CI likec4 switches to a timestamped,
+# ANSI-coloured reporter that the anchored DIAG_RE below cannot match, and a syntax error
+# would then publish a truncated model at rc 0 (measured under CI=true). ANSI is also
+# stripped from the log as a second line of defence.
+if ! ( cd "$DIAGRAMS_DIR" && env -u CI -u FORCE_COLOR NO_COLOR=1 npx -y --ignore-scripts --before="${LIKEC4_BEFORE}" "likec4@${LIKEC4_VERSION}" export json --no-use-dot -o "$TMP/model.likec4.json" . ) >"$RENDER_LOG" 2>&1; then
+  echo "ERROR: likec4 export exited non-zero — refusing to overwrite $OUT" >&2
+  cat "$RENDER_LOG" >&2
+  exit 1
+fi
+
+# exit-0 is NOT proof. likec4@1.50.0 has TWO source-fault modes that both exit 0:
+#   (1) unresolved reference / missing spec.c4 -> an EMPTY-elements model
+#       (the #4966 case; see apps/web-platform/server/c4-render.ts).
+#   (2) a syntax error -> likec4 recovers by dropping the bad fragment, prints
+#       `Invalid <file>` + `Line N:` (or `Could not resolve …`), and STILL emits
+#       a non-empty (now-incomplete) model — so element-count alone misses it.
+# Gate on ALL of: a clean diagnostic stream, a non-empty elements map, and a
+# non-empty views map. Element-count is the version-robust backstop; the
+# diagnostic grep catches mode (2); the views gate catches the container/
+# graphviz-fallback shape (#8861). On error we never publish, so a broken .c4
+# can never clobber the good committed artifact.
+# Anchors keep the markers off the workspace-path line likec4 echoes (`workspace:
+# /abs/path …`): `^Invalid ` and the indented `Line N:` form (`    Line 274:`)
+# can't match a repo path, so a checkout dir containing those substrings can't
+# false-FAIL. `Could not resolve` is a distinctive likec4 phrase.
+DIAG_RE='^([0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)? +[A-Z]+ +[^ ]+ +)?Invalid |Could not resolve|^[[:space:]]+Line [0-9]+:'
+_esc="$(printf '\033')"
+sed "s/${_esc}\[[0-9;]*m//g" "$RENDER_LOG" >"$RENDER_LOG.plain" && mv -f "$RENDER_LOG.plain" "$RENDER_LOG"
+if grep -qE "$DIAG_RE" "$RENDER_LOG"; then
+  echo "ERROR: likec4 reported a source validation error — refusing to overwrite $OUT" >&2
+  grep -E "$DIAG_RE" "$RENDER_LOG" >&2
+  echo "       Fix the .c4 source (run: cd $DIAGRAMS_DIR && npx -y likec4@${LIKEC4_VERSION} validate --no-use-dot .)" >&2
+  exit 1
+fi
+if ! jq -e '(.elements | objects | length) > 0' "$TMP/model.likec4.json" >/dev/null 2>&1; then
+  echo "ERROR: likec4 produced an empty/degenerate model — refusing to overwrite $OUT" >&2
+  echo "       Fix the .c4 source (run: cd $DIAGRAMS_DIR && npx -y likec4@${LIKEC4_VERSION} validate --no-use-dot .)" >&2
+  exit 1
+fi
+# Elements-but-no-views is OUR layout failing, never the user's source (#8740):
+# a successful layout always emits at least `index`, even with no `views {}`
+# block. `objects | length` shares the server's plain-object semantics — a
+# non-object `views` (string/array) counts 0 here as it does in
+# c4ModelCounts/plainObjectSize — so a malformed export is refused, not
+# published. Keep both writers' predicates strict in lockstep.
+if ! jq -e '(.views | objects | length) > 0' "$TMP/model.likec4.json" >/dev/null 2>&1; then
+  echo "ERROR: likec4 produced a model with elements but no views — a layout failure, not a .c4 source fault — refusing to overwrite $OUT" >&2
+  tail -20 "$RENDER_LOG" >&2
+  echo "       Do NOT edit the .c4 source: retry the render; if it persists, reproduce with: cd $DIAGRAMS_DIR && npx -y likec4@${LIKEC4_VERSION} export json --no-use-dot ." >&2
+  exit 1
+fi
+
+# Canonicalize AFTER all gates (never instead of them): one JSON value per
+# line with every view `hash` blanked, so git can merge two regenerations whose
+# edits touch different values (ADR-235, #8542). Node serializes, never jq —
+# jq reformats numbers. The web app (c4-render.ts) and the plugin
+# (generate-c4-from-components.ts) emit these same bytes through the same
+# module, so no writer reformats another's file.
+if ! node "$CANONICAL_CLI" "$TMP/model.likec4.json" >"$TMP/canonical.json"; then
+  echo "ERROR: could not canonicalize the rendered model — refusing to overwrite $OUT" >&2
+  exit 1
+fi
+
+# Publish only on success, atomically: copy into the destination directory then
+# rename. An intra-filesystem rename is atomic, so a crash mid-write can never
+# leave a truncated model.likec4.json on the tracked path (a bare `cp` onto $OUT
+# is not atomic). The temp lands beside $OUT (a dotfile, never a tracked .c4) so
+# the rename stays on one filesystem; the EXIT trap reaps it if cp/mv aborts.
+OUT_DIR="$(dirname "$OUT")"
+mkdir -p "$OUT_DIR"
+PUBLISH_TMP="$(mktemp "$OUT_DIR/.model.likec4.json.XXXXXX")"
+cp "$TMP/canonical.json" "$PUBLISH_TMP"
+mv -f "$PUBLISH_TMP" "$OUT"
+PUBLISH_TMP=""  # renamed onto $OUT — nothing left for the trap to clean
+echo "Regenerated $OUT ($(jq '.elements | length' "$OUT") elements, $(jq '.relations | length' "$OUT") relations, $(jq '.views | length' "$OUT") views)"

package/scripts/resolve-git-root.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+
+# resolve-git-root.sh -- Sourceable helper to detect bare repos and resolve GIT_ROOT
+#
+# Usage: source this file. It sets GIT_ROOT, GIT_COMMON_ROOT, and IS_BARE.
+# Do NOT execute directly.
+#
+# Variables set:
+#   GIT_ROOT        -- absolute path to the repository root (bare or non-bare)
+#   GIT_COMMON_ROOT -- absolute path to the shared repo root across all worktrees
+#                      (equals GIT_ROOT when not in a worktree)
+#   IS_BARE         -- "true" or "false"
+#
+# On error (not inside a git repo), returns 1 without calling exit.
+# Does not call set or modify the caller's shell options.
+
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  echo "Error: resolve-git-root.sh must be sourced, not executed." >&2
+  echo "Usage: source path/to/resolve-git-root.sh" >&2
+  exit 1
+fi
+
+IS_BARE=false
+if [[ "$(git rev-parse --is-bare-repository 2>/dev/null)" == "true" ]]; then
+  IS_BARE=true
+  _resolve_git_dir=$(git rev-parse --absolute-git-dir 2>/dev/null)
+  if [[ "$_resolve_git_dir" == */.git ]]; then
+    GIT_ROOT="${_resolve_git_dir%/.git}"
+  else
+    GIT_ROOT="$_resolve_git_dir"
+  fi
+  unset _resolve_git_dir
+else
+  GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || {
+    echo "Error: Not inside a git repository." >&2
+    return 1
+  }
+fi
+
+# Validate that GIT_ROOT resolves to an actual directory
+if [[ ! -d "$GIT_ROOT" ]]; then
+  echo "Error: GIT_ROOT resolved to non-existent path: $GIT_ROOT" >&2
+  return 1
+fi
+
+# Resolve common root (shared across worktrees)
+# git rev-parse --git-common-dir returns the shared .git dir; may be relative,
+# so cd+pwd resolves to absolute. Strip trailing /.git for the repo root.
+_resolve_common_dir=$(cd "$(git rev-parse --git-common-dir 2>/dev/null)" && pwd)
+if [[ "$_resolve_common_dir" == */.git ]]; then
+  GIT_COMMON_ROOT="${_resolve_common_dir%/.git}"
+else
+  GIT_COMMON_ROOT="$_resolve_common_dir"
+fi
+unset _resolve_common_dir

package/scripts/resolve-regenerable-conflicts.sh

@@ -0,0 +1,363 @@
+#!/usr/bin/env bash
+# resolve-regenerable-conflicts.sh — complete a merge whose ONLY conflicts are on generated
+# artifacts, by regenerating them from the merged sources.
+#
+# Usage: bash "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-regenerable-conflicts.sh" <base-ref>
+#        (run from inside the repository being merged)
+#
+# WHY THIS EXISTS (#8377, ADR-235). A generated file that is COMMITTED conflicts with every
+# other branch that regenerates it, and side-picking is always wrong: `--ours` and `--theirs`
+# each produce an artifact that matches neither side's sources. The correct resolution is to
+# take the merged SOURCES and re-run the generator over them. The one such product is
+# knowledge-base/engineering/architecture/diagrams/model.likec4.json, which the web-platform C4
+# viewer fetches as a committed blob (apps/web-platform/app/api/kb/c4/project/route.ts).
+#
+# ── THE CONTRACT: TWO OUTCOMES ─────────────────────────────────────────────────────────────
+#   exit 0       the merge completed and was COMMITTED. The caller may push.
+#   exit non-0   nothing was touched. The tree is byte-identical to entry.
+# Every exit prints one stdout line `SOLEUR_REGEN_ON_CONFLICT … rc=N` (rc=1 carries
+# class=na|failed|interrupted and a reason slug) and, on refusal, one human line on stderr
+# prefixed `[regen-on-conflict]` naming the next action.
+#
+# ── HOW: RENDER FROM GIT OBJECTS FIRST, TOUCH THE WORKTREE LAST (ADR-235 amendment 2026-09-23)
+#   1. `git merge-tree` computes the merge without touching anything and yields the merged TREE.
+#   2. The tracked, cleanly-merged LikeC4 sources are copied out of that tree's OBJECTS into a
+#      private staging dir, and the renderer runs there. Nothing untracked, ignored, symlinked
+#      or configured in the worktree can reach the render, and the renderer cannot write the
+#      worktree. Every render failure, timeout or kill therefore happens with the tree untouched.
+#   3. Only then: re-check nothing moved, `git merge --no-commit`, write the rendered bytes,
+#      assert the index is exactly the merged tree plus those bytes, commit, and assert no commit
+#      hook changed the result.
+#
+# NEVER PUSHES — callers own the push. NO LOCK — per-worktree index/HEAD/MERGE_HEAD serialise
+# runs within a worktree; the HEAD and clean-tree re-checks make a lost race refuse.
+set -uo pipefail
+
+# The PLUGIN directory: this script's own, made absolute before any `cd` (ADR-179 A17).
+_plugin_scripts_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd -P)" || _plugin_scripts_dir=""
+readonly PLUGIN_SCRIPTS_DIR="$_plugin_scripts_dir"
+
+# Shared context-sanitize lib (#10395), beside this script under lib/. When it
+# is unreadable the same-name fallbacks carry each site's pre-change strip set —
+# never weaker than today.
+_ctx_lib="${PLUGIN_SCRIPTS_DIR:-/nonexistent}/lib/context-sanitize.sh"
+# shellcheck source=/dev/null
+[[ -r "$_ctx_lib" ]] && . "$_ctx_lib" || true
+declare -F soleur_ctx_sanitize >/dev/null 2>&1 \
+  || soleur_ctx_sanitize() { LC_ALL=C tr -d '\000-\037\177'; }
+declare -F soleur_ctx_sanitize_nl >/dev/null 2>&1 \
+  || soleur_ctx_sanitize_nl() { LC_ALL=C tr -d '\000-\011\013-\037\177'; }
+# The REPO: the caller's, from the CWD — never BASH_SOURCE/../.., which is the plugin.
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+
+# The render budget, matching generate-c4-from-components.ts (a cold npx install measured 151s).
+REGEN_TIMEOUT_S=600
+BASE=""; BASE_SHA=""; HEAD_SHA=""; ARM=""; ROOT_SRC="-"
+WORK=""; RENDER_PID=""; MERGING=0
+
+# One line per exit for machines (stdout), one for humans (stderr).
+_marker() { printf 'SOLEUR_REGEN_ON_CONFLICT rc=1 class=%s reason=%s\n' "$1" "$2"; }
+# Strip control characters: the tail of a renderer log is attacker-influenced text.
+_clean() { soleur_ctx_sanitize_nl | tail -n 4 | tr '\n' '|' | sed 's/|$//; s/|/ | /g'; }
+
+# na <slug> <message> — refuse before anything was touched.
+na() { _marker na "$1"; echo "[regen-on-conflict] not applicable: $2" >&2; exit 1; }
+# fail <slug> <message> — a regeneration problem, still before anything was touched.
+fail() { _marker failed "$1"; echo "[regen-on-conflict] regen failed: $2" >&2; exit 1; }
+# bail <slug> <message> — refuse AFTER the merge started: unwind, and VERIFY the unwind.
+# BAIL_CLASS is `failed` except for a signal, which reports `interrupted` wherever it lands.
+BAIL_CLASS=failed
+bail() {
+  _marker "$BAIL_CLASS" "$1"
+  local unwound="merge aborted, nothing committed"
+  [[ -n "$REPO_ROOT" ]] && git -C "$REPO_ROOT" merge --abort 2>/dev/null
+  if [[ -n "$REPO_ROOT" && -f "$(git -C "$REPO_ROOT" rev-parse --git-dir 2>/dev/null)/MERGE_HEAD" ]]; then
+    unwound="could NOT unwind: a merge is still in progress — run: git merge --abort"
+  fi
+  echo "[regen-on-conflict] regen failed: $2 — $unwound" >&2
+  exit 1
+}
+
+# Canonical copy of test-helpers.sh's assert_fixture_dir (P1a pins every tracked copy byte-equal;
+# the P1b scanner recognises only this name). Here it backstops the staging parent, which the
+# explicit `case` before it already refuses with a marker — its bare exit 2 is not reached.
+assert_fixture_dir() {
+  case "${1-}" in
+    "") printf 'FATAL: fixture dir is EMPTY; git -C "" would operate on %s\n' "$PWD" >&2; exit 2 ;;
+    */../*|*/..) printf 'FATAL: fixture dir %s contains ..; refusing\n' "$1" >&2; exit 2 ;;
+    /proc/*|/sys/*|/dev/*) printf 'FATAL: fixture dir %s is a synthetic-fs path; refusing\n' "$1" >&2; exit 2 ;;
+    /|//|/.) printf 'FATAL: fixture dir resolves to the filesystem root; refusing\n' >&2; exit 2 ;;
+    /*) : ;;
+    *)  printf 'FATAL: fixture dir %s is RELATIVE; refusing\n' "$1" >&2; exit 2 ;;
+  esac
+}
+
+_cleanup() {
+  [[ -n "$RENDER_PID" ]] && kill -TERM "$RENDER_PID" 2>/dev/null
+  [[ -n "$WORK" && -d "$WORK" ]] && rm -rf -- "$WORK"
+}
+_on_signal() {
+  if [[ "$MERGING" -eq 1 ]]; then
+    BAIL_CLASS=interrupted; bail interrupted "interrupted during the merge"
+  fi
+  _cleanup
+  _marker interrupted signal
+  echo "[regen-on-conflict] interrupted — nothing was touched; re-run when ready" >&2
+  exit 1
+}
+trap _cleanup EXIT
+trap _on_signal INT TERM HUP
+
+[[ -n "$REPO_ROOT" ]] || na not-a-repo "not inside a git work tree — cd into the repository being merged and re-run"
+
+# plugin_root -> sets PLUGIN_ROOT and ROOT_SRC (no subshell, so both survive), or returns 1 with
+# the reason in PLUGIN_ROOT_WHY. The sibling wins; a bare ${CLAUDE_PLUGIN_ROOT}
+# (no `:-`, ADR-179 A12) is read only when it is absent. The plugin.json check is a sanity
+# check, not a boundary (ADR-179 A11, A17).
+PLUGIN_ROOT=""; PLUGIN_ROOT_WHY=""
+plugin_root() {
+  local root=""
+  if [[ -n "$PLUGIN_SCRIPTS_DIR" && -f "$PLUGIN_SCRIPTS_DIR/render-c4-model.sh" ]]; then
+    root="$(cd "$PLUGIN_SCRIPTS_DIR/.." 2>/dev/null && pwd -P)" || root=""
+    ROOT_SRC="sibling"
+  elif [[ -n "${CLAUDE_PLUGIN_ROOT+set}" && "${CLAUDE_PLUGIN_ROOT}" == /* ]]; then
+    root="$(cd "${CLAUDE_PLUGIN_ROOT}" 2>/dev/null && pwd -P)" || root=""
+    ROOT_SRC="env"
+    if [[ -z "$root" || ! -f "$root/scripts/render-c4-model.sh" ]]; then
+      PLUGIN_ROOT_WHY="CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT} has no scripts/render-c4-model.sh"
+      return 1
+    fi
+  else
+    PLUGIN_ROOT_WHY="no render-c4-model.sh beside this resolver and no absolute CLAUDE_PLUGIN_ROOT"
+    return 1
+  fi
+  [[ -n "$root" ]] || { PLUGIN_ROOT_WHY="could not resolve the plugin root"; return 1; }
+  if ! grep -q '"name"[[:space:]]*:[[:space:]]*"soleur"' "$root/.claude-plugin/plugin.json" 2>/dev/null; then
+    PLUGIN_ROOT_WHY="$root/.claude-plugin/plugin.json does not name soleur"
+    return 1
+  fi
+  PLUGIN_ROOT="$root"
+}
+
+# ── THE RESOLVABLE SET ─────────────────────────────────────────────────────────────────────
+# One hardcoded member, not a manifest (ADR-235: a manifest is a parse surface and invites
+# re-tracking generated files). The test seam is ARGV-only (--test-resolvable <tsv>): an
+# inherited env var reaching an unattended commit was a demonstrated command channel (#8384).
+# Each argv-producing line carries an ARGV-SOURCE marker; the suite pins the set. An arm's argv
+# is a PREFIX: the resolver appends `--root <staging> --out <file>`.
+RESOLVABLE_PATHS=()
+RESOLVABLE_ARGVS=()   # one TAB-joined argv prefix per path, index-aligned with the above
+if [[ "${1:-}" == "--test-resolvable" ]]; then
+  _tsv="${2:-}"
+  [[ -f "$_tsv" ]] || na bad-args "--test-resolvable: '$_tsv' is not a file"
+  while IFS=$'\t' read -r _p _rest; do
+    [[ -n "$_p" ]] || continue
+    RESOLVABLE_PATHS+=("$_p"); RESOLVABLE_ARGVS+=("$_rest")  # ARGV-SOURCE: test-seam
+  done < "$_tsv"
+  shift 2
+  ARM="test-seam"
+else
+  RESOLVABLE_PATHS=("knowledge-base/engineering/architecture/diagrams/model.likec4.json")  # RESOLVABLE-SET: default
+  ARM="plugin"
+fi
+
+BASE="${1:-}"
+[[ -n "$BASE" ]] || na bad-args "no base ref given — re-run as: resolve-regenerable-conflicts.sh <base-ref> (e.g. origin/main)"
+cd "$REPO_ROOT" || na not-a-repo "cannot enter repo root $REPO_ROOT"
+BASE_SHA="$(git rev-parse --verify --quiet "$BASE^{commit}")" \
+  || na bad-base "base ref '$BASE' does not resolve to a commit — git fetch it first"
+HEAD_SHA="$(git rev-parse --verify --quiet HEAD)" || na no-head "HEAD does not resolve to a commit"
+
+# _clean_or_why -> empty when the tree is clean for our purposes, else the reason.
+# MERGE_HEAD first (its remedy differs). `-uall` so status.showUntrackedFiles=no cannot hide an
+# untracked file; `--ignored` is NOT used — ignored files are invisible to the merge unless the
+# merged tree adds the same path, which _collisions checks.
+_clean_or_why() {
+  [[ ! -f "$(git rev-parse --git-dir)/MERGE_HEAD" ]] || { printf 'a merge is already in progress — finish it or run git merge --abort'; return; }
+  local st; st="$(git status --porcelain --untracked-files=all)"
+  [[ -z "$st" ]] || printf 'working tree is not clean (%s) — commit or discard your changes' \
+    "$(printf '%s\n' "$st" | head -n1 | cut -c4- | soleur_ctx_sanitize | cut -c1-200)"
+}
+_why="$(_clean_or_why)"; [[ -z "$_why" ]] || na dirty-tree "$_why, then re-run"
+
+# ── CLASSIFY: merge-tree, NUL-framed ───────────────────────────────────────────────────────
+# A relative XDG_CACHE_HOME is invalid and ignored (XDG Base Directory spec): relative to which cwd?
+_cache="${XDG_CACHE_HOME:-}"; [[ "$_cache" == /* ]] || _cache="${HOME:-/nonexistent}/.cache"
+case "$_cache" in
+  */../*|*/..|/proc/*|/sys/*|/dev/*|/|//|/.) fail no-staging "unusable cache dir for staging ($_cache) — set XDG_CACHE_HOME to a normal absolute directory" ;;
+  /*) : ;;
+  *) fail no-staging "HOME is not an absolute path ($_cache)" ;;
+esac
+assert_fixture_dir "$_cache"
+WORK_PARENT="$_cache/soleur"
+if mkdir -p "$WORK_PARENT" 2>/dev/null && chmod 700 "$WORK_PARENT" 2>/dev/null && WORK="$(mktemp -d "$WORK_PARENT/regen.XXXXXX")"; then :
+else fail no-staging "cannot create a private staging dir under $WORK_PARENT"; fi
+chmod 700 "$WORK"
+
+mt_rc=0
+git merge-tree --write-tree -z --name-only "$BASE_SHA" "$HEAD_SHA" >"$WORK/mt" 2>"$WORK/mt.err" || mt_rc=$?
+[[ "$mt_rc" -ne 0 ]] || na no-conflict "no conflict between HEAD and $BASE — nothing to resolve; merge it normally"
+if [[ "$mt_rc" -ge 2 ]]; then
+  grep -q 'unknown option\|usage: git merge-tree' "$WORK/mt.err" 2>/dev/null \
+    && na old-git "git merge-tree --write-tree needs git >= 2.38 (you have $(git --version | cut -d' ' -f3)) — upgrade git, or resolve by hand"
+  na merge-tree-failed "git merge-tree failed (rc=$mt_rc): $(_clean <"$WORK/mt.err")"
+fi
+
+# Records: <tree> NUL, conflicted paths NUL…, empty NUL, then messages as
+# <N> NUL <N paths> NUL <type> NUL <text> NUL. Only a CONFLICT (contents) is resolvable: every
+# other kind (modify/delete, rename/rename, add/add, distinct types) decides whether a file
+# should EXIST, which regenerating cannot answer.
+TREE=""; conflicted=(); content_ok=$'\x1f'
+_state=tree; _n=0; _mpaths=()
+while IFS= read -r -d '' rec; do
+  case "$_state" in
+    tree) TREE="$rec"; _state=paths ;;
+    paths) if [[ -z "$rec" ]]; then _state=count; else conflicted+=("$rec"); fi ;;
+    count)
+      _n="$rec"; _mpaths=()
+      [[ "$_n" =~ ^[0-9]+$ ]] || na merge-tree-format "unparseable merge-tree output"
+      if [[ "$_n" -eq 0 ]]; then _state="type"; else _state="mpath"; fi ;;
+    mpath) _mpaths+=("$rec"); [[ "${#_mpaths[@]}" -lt "$_n" ]] || _state="type" ;;
+    type) _type="$rec"; _state=text ;;
+    text)
+      case "$_type" in
+        "CONFLICT (contents)") for _mp in ${_mpaths[@]+"${_mpaths[@]}"}; do content_ok+="$_mp"$'\x1f'; done ;;
+        CONFLICT*) na unresolvable-kind "$(printf '%s' "$rec" | _clean) — resolve this merge by hand" ;;
+      esac
+      _state=count ;;
+  esac
+done <"$WORK/mt"
+[[ "$TREE" =~ ^[0-9a-f]{40,64}$ && "${#conflicted[@]}" -gt 0 ]] \
+  || na merge-tree-format "merge-tree reported rc=$mt_rc but no conflicted path was parsed"
+
+_argv_for() {  # <path> -> echoes the TAB-joined argv prefix, or returns 1
+  local i
+  for i in "${!RESOLVABLE_PATHS[@]}"; do
+    [[ "${RESOLVABLE_PATHS[$i]}" == "$1" ]] && { printf '%s' "${RESOLVABLE_ARGVS[$i]:-}"; return 0; }
+  done
+  return 1
+}
+for p in "${conflicted[@]}"; do
+  [[ "$content_ok" == *$'\x1f'"$p"$'\x1f'* ]] \
+    || na unresolvable-kind "$p is not a plain content conflict — resolve this merge by hand"
+  _argv_for "$p" >/dev/null || na not-regenerable "conflicted path is not regenerable: $p — resolve this merge by hand"
+done
+
+# The production arm is resolved only now that a regenerable conflict exists.
+if [[ "$ARM" == "plugin" ]]; then
+  plugin_root \
+    || fail no-plugin-root "no usable Soleur plugin root ($PLUGIN_ROOT_WHY) — set CLAUDE_PLUGIN_ROOT to the installed plugin (the directory whose .claude-plugin/plugin.json names soleur) and re-run"
+  RESOLVABLE_ARGVS=("$(printf 'bash\t%s' "$PLUGIN_ROOT/scripts/render-c4-model.sh")")  # ARGV-SOURCE: plugin
+fi
+
+# ── STAGE: tracked sources out of the merged tree's objects ────────────────────────────────
+# Allowlist, not blocklist: only regular-file LikeC4 sources are copied. A symlink or gitlink
+# anywhere under the directory, or a likec4 config (which likec4 would load, the js/ts forms as
+# code), is REFUSED rather than skipped — rendering without it would not be the repo's model.
+assert_fixture_dir "$_cache"; assert_fixture_dir "$REPO_ROOT"   # re-stated for fixture-scan's window
+STAGE="$WORK/root"; OUT="$WORK/out"; mkdir -p "$STAGE" "$OUT"
+_staged_dirs=$'\x1f'
+for p in "${conflicted[@]}"; do
+  _dir="$(dirname -- "$p")"
+  [[ "$_staged_dirs" == *$'\x1f'"$_dir"$'\x1f'* ]] && continue
+  _staged_dirs+="$_dir"$'\x1f'
+  git ls-tree -r -z --full-tree "$TREE" -- "$_dir/" >"$WORK/ls" 2>/dev/null \
+    || fail stage-failed "could not list $_dir in the merged tree"
+  while IFS= read -r -d '' ent; do
+    _meta="${ent%%$'\t'*}"; _path="${ent#*$'\t'}"
+    _mode="${_meta%% *}"; _obj="${_meta##* }"
+    case "/$_path/" in */../*|*/./*) na unsafe-path "refusing path $_path in the merged tree" ;; esac
+    case "$_mode" in
+      120000) na symlink-source "$_path is a symlink in the merged tree — the renderer would follow it outside the merge; replace it with a regular file" ;;
+      160000) na gitlink-source "$_path is a submodule in the merged tree — its sources are not part of the merge" ;;
+    esac
+    case "${_path##*/}" in
+      likec4.config.*|.likec4rc|.likec4.config.json)
+        na likec4-config "$_path would configure the render (the .js/.ts forms run as code) — regenerate by hand" ;;
+    esac
+    [[ "$_mode" == 100644 || "$_mode" == 100755 ]] || continue
+    case "$_path" in
+      *.c4|*.likec4|*.like-c4)
+        mkdir -p "$STAGE/$(dirname -- "$_path")"
+        git cat-file blob "$_obj" >"$STAGE/$_path" || fail stage-failed "could not read $_path from the merged tree"
+        chmod 600 "$STAGE/$_path" ;;
+    esac
+  done <"$WORK/ls"
+done
+for p in "${conflicted[@]}"; do
+  _m="$(git ls-tree -z --full-tree "$TREE" -- "$p" | cut -d' ' -f1)"
+  [[ "$_m" == 100644 || "$_m" == 100755 ]] || na not-a-file "$p is not a regular file in the merged tree — resolve this merge by hand"
+done
+
+# ── RENDER, in the background so a signal is handled at once ──────────────────────────────
+_to=()
+if command -v timeout >/dev/null 2>&1; then _to=(timeout -k 10 "$REGEN_TIMEOUT_S")
+elif command -v gtimeout >/dev/null 2>&1; then _to=(gtimeout -k 10 "$REGEN_TIMEOUT_S"); fi
+outs=()
+for i in "${!conflicted[@]}"; do
+  p="${conflicted[$i]}"
+  IFS=$'\t' read -r -a _argv <<<"$(_argv_for "$p")"
+  [[ "${#_argv[@]}" -gt 0 ]] || fail empty-command "empty regeneration command for $p"
+  out="$OUT/$i"; outs+=("$out")
+  echo "[regen-on-conflict] regenerating $p (runs likec4 through npx; a cold cache takes minutes)" >&2
+  ${_to[@]+"${_to[@]}"} "${_argv[@]}" --root "$STAGE" --out "$out" >"$WORK/log.$i" 2>&1 &
+  RENDER_PID=$!
+  _rc=0; wait "$RENDER_PID" || _rc=$?
+  RENDER_PID=""
+  if [[ "$_rc" -ne 0 ]]; then
+    _w="exited $_rc"; [[ "$_rc" -eq 124 && "${#_to[@]}" -gt 0 ]] && _w="timed out after ${REGEN_TIMEOUT_S}s"
+    fail render-failed "the renderer $_w for $p: $(_clean <"$WORK/log.$i")"
+  fi
+  [[ -s "$out" ]] || fail no-output "the renderer did not produce $p"
+  ! grep -qE '^(<{7}|={7}|>{7})( |$)' -- "$out" || fail markers "the rendered $p still contains conflict markers"
+done
+
+# ── APPLY: only now is the worktree touched ────────────────────────────────────────────────
+[[ "$(git rev-parse --verify --quiet HEAD)" == "$HEAD_SHA" ]] \
+  || na head-moved "HEAD moved during the render — nothing was touched; re-run"
+_why="$(_clean_or_why)"; [[ -z "$_why" ]] || na dirty-tree "the worktree changed during the render ($_why) — nothing was touched; re-run"
+# A path the merge ADDS that exists on disk (untracked or ignored) would be overwritten.
+while IFS= read -r -d '' _a; do
+  [[ -e "$_a" || -L "$_a" ]] && na would-overwrite "the merge adds $_a, which exists here untracked or ignored — move it aside and re-run"
+done < <(git diff -z --name-only --diff-filter=A "$HEAD_SHA" "$TREE")
+
+MERGING=1
+merge_err="$(git merge --no-ff --no-commit -m "Merge $BASE (${BASE_SHA:0:12}); regenerated ${conflicted[*]}" "$BASE_SHA" 2>&1 >/dev/null)" || true
+if [[ ! -f "$(git rev-parse --git-dir)/MERGE_HEAD" ]]; then
+  bail merge-not-started "the merge did not start: $(printf '%s' "${merge_err:-no output}" | _clean)"
+fi
+for i in "${!conflicted[@]}"; do
+  p="${conflicted[$i]}"
+  [[ ! -L "$p" ]] || bail symlink-artifact "refusing to write through symlink $p"
+  cp -- "$OUT/$i" "$REPO_ROOT/$p" && git add -- "$p" || bail stage-failed "could not write $p"
+  [[ "$(git rev-parse ":$p")" == "$(git hash-object --path="$p" -- "${outs[$i]}")" ]] \
+    || bail staged-mismatch "the staged $p is not the rendered bytes"
+done
+[[ -z "$(git diff --name-only --diff-filter=U)" ]] || bail residual-conflict "conflicts remain after regeneration"
+# The index must be exactly the merged tree plus the regenerated paths — nothing else.
+_want="$(printf '%s\n' "${conflicted[@]}" | LC_ALL=C sort)"
+_got="$(git diff --cached -z --name-only "$TREE" | tr '\0' '\n' | LC_ALL=C sort)"
+[[ "$_got" == "$_want" ]] || bail index-mismatch "the index differs from the merged tree beyond the regenerated paths: $(printf '%s' "$_got" | _clean)"
+
+_expect_tree="$(git write-tree)" || bail write-tree "could not write the index tree"
+# From here a signal is RECORDED, not acted on: the commit either lands or fails on its own, and
+# the marker must describe the repo as it is. The default disposition would exit with no marker.
+_sig_late=""
+trap '_sig_late=1' INT TERM HUP
+commit_err="$(git commit --no-edit 2>&1 >/dev/null)" \
+  || bail commit-failed "the merge commit failed: $(printf '%s' "$commit_err" | _clean)"
+MERGING=0
+if [[ "$(git rev-parse "HEAD^{tree}")" != "$_expect_tree" || "$(git rev-parse HEAD^1)" != "$HEAD_SHA" \
+      || "$(git rev-parse HEAD^2 2>/dev/null)" != "$BASE_SHA" ]]; then
+  _undone="it was undone"
+  if ! git reset -q --keep "$HEAD_SHA" 2>/dev/null || [[ "$(git rev-parse HEAD)" != "$HEAD_SHA" ]]; then
+    _undone="could NOT undo it (reset --keep refused; the hook left local edits) — HEAD is the rejected merge commit; review, then run: git reset --keep $HEAD_SHA"
+  fi
+  _marker failed commit-hook-changed-tree
+  echo "[regen-on-conflict] regen failed: a commit hook changed the merge commit — $_undone; resolve by hand" >&2
+  exit 1
+fi
+[[ -z "$_sig_late" ]] || echo "[regen-on-conflict] a signal arrived during git commit; the commit had already completed and is verified" >&2
+
+csv="$(IFS=,; printf '%s' "${conflicted[*]}")"
+printf 'SOLEUR_REGEN_ON_CONFLICT paths=%s arm=%s root_src=%s rc=0\n' "$csv" "$ARM" "$ROOT_SRC"