trae-coding-engine 0.1.0

package/templates/scripts/open-mr.sh

@@ -0,0 +1,536 @@
+#!/usr/bin/env bash
+# Open or refresh a Codebase MR for the current branch and apply a
+# model-written description.
+#
+# See AGENTS.md §"MR description" for the rule this script enforces.
+
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+usage() {
+  cat <<'USAGE'
+Open or refresh a Codebase MR for the current branch and apply a model-written
+description when one is provided.
+
+Usage:
+  scripts/open-mr.sh --title "<conventional-commit title>"
+  scripts/open-mr.sh --title "<conventional-commit title>" --body-file /tmp/mr-desc.md
+  scripts/open-mr.sh --title "feat(scope): subject" --base release --draft --body-file /tmp/mr-desc.md
+  scripts/open-mr.sh --title "feat(scope): subject" --repo epscp/coding_engine --body-file /tmp/mr-desc.md
+  scripts/open-mr.sh --body-file /tmp/mr-desc.md  # refresh-only (MR must already exist)
+
+Options:
+  --title <text>     MR title (required when creating; updates title if MR exists)
+  --base <branch>    Target branch (default: bytedcli's repo default, usually `release`)
+  -R, --repo <path>  Codebase repository path, e.g. epscp/coding_engine
+  --body-file <path> Model-written MR description following the project template
+  --body-stdin       Read the model-written MR description from stdin
+  --actor <mode>     MR API mode: human|agent.
+                     human: bytedcli (default).
+                     agent: codebase CLI with CODEBASE_CI_APP_* or CODEBASE_CLI_APP_*.
+  --force            Overwrite a hand-written MR description
+  --draft            Create as draft
+  --dry-run          Skip create/update; print what would happen
+  -h, --help         Show this help
+
+Behavior:
+  1. Refuse to run from a protected branch (release / main / master) or
+     detached HEAD.
+  2. Push the current branch with `-u origin` when no upstream is set.
+  3. Detect an existing MR for this branch via `bytedcli codebase mr get`.
+     If one exists, skip create and proceed to step 4 (refresh-only mode).
+  4. Otherwise create the MR with `--title` only (no inline body) so the
+     project template is preserved.
+  5. If a body is provided, apply it. If no body is provided, leave the
+     default/current MR description unchanged for manual editing.
+
+Per AGENTS.md §"MR description": this is the **preferred** entry point for
+opening a new MR. Agents should pass a model-written body with --body-file or
+--body-stdin. Humans may omit the body so Codebase loads the default template
+for manual editing. Direct `bytedcli codebase mr create --body "<heredoc>"` is
+forbidden because it bypasses the template.
+Agents should draft the body from the actual branch diff and validation
+evidence.
+
+Requires: python3, git, and bytedcli. Agent mode also requires codebase for MR
+create/list/edit; issue status updates still use bytedcli codebase.
+Agent-created MRs also best-effort rerun failed pipeline checks through the
+current bytedcli human/PAT identity when scripts/rerun-mr-checks-as-human.sh is
+available. Set CODING_MR_AUTO_RERUN_CHECKS=0 to skip that step.
+USAGE
+}
+
+TITLE=""
+BASE=""
+REPO=""
+DRAFT_FLAG=""
+DRY_RUN=0
+BODY_FILE=""
+BODY_STDIN=0
+FORCE=0
+ACTOR="${CODING_ISSUE_AUTODEV_ACTOR:-human}"
+
+# shellcheck source=scripts/lib/cli-args.sh
+. scripts/lib/cli-args.sh
+# shellcheck source=scripts/lib/codebase-json.sh
+. scripts/lib/codebase-json.sh
+# shellcheck source=scripts/lib/codebase-actor.sh
+. scripts/lib/codebase-actor.sh
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --title) TITLE=$(require_value --title "${2:-}"); shift 2 ;;
+    --title=*) TITLE="${1#--title=}"; shift ;;
+    --base) BASE=$(require_value --base "${2:-}"); shift 2 ;;
+    --base=*) BASE="${1#--base=}"; shift ;;
+    -R|--repo) REPO=$(require_value --repo "${2:-}"); shift 2 ;;
+    --repo=*) REPO="${1#--repo=}"; shift ;;
+    --body-file) BODY_FILE=$(require_value --body-file "${2:-}"); shift 2 ;;
+    --body-file=*) BODY_FILE="${1#--body-file=}"; shift ;;
+    --body-stdin) BODY_STDIN=1; shift ;;
+    --actor) ACTOR=$(require_value --actor "${2:-}"); shift 2 ;;
+    --actor=*) ACTOR="${1#--actor=}"; shift ;;
+    --force) FORCE=1; shift ;;
+    --draft) DRAFT_FLAG="--draft"; shift ;;
+    --dry-run) DRY_RUN=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "unknown arg: $1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+if [ "$BODY_STDIN" -eq 1 ] && [ -n "$BODY_FILE" ]; then
+  echo "error: use only one of --body-file or --body-stdin" >&2
+  exit 2
+fi
+if [ -n "$BODY_FILE" ] && [ ! -f "$BODY_FILE" ]; then
+  echo "error: --body-file does not exist: $BODY_FILE" >&2
+  exit 2
+fi
+BODY_PROVIDED=0
+if [ "$BODY_STDIN" -eq 1 ] || [ -n "$BODY_FILE" ]; then
+  BODY_PROVIDED=1
+fi
+
+codebase_json_require
+for cmd in git grep awk; do
+  command -v "$cmd" >/dev/null || { echo "missing dependency: $cmd" >&2; exit 1; }
+done
+codebase_actor_require_cli "$ACTOR"
+if [ "$ACTOR" = "agent" ]; then
+  command -v codebase >/dev/null || { echo "missing dependency: codebase" >&2; exit 1; }
+fi
+codebase_actor_set_repo_args "$REPO"
+
+codebase_mr_for_branch() {
+  codebase_actor_configure_app_env
+  local raw
+  if ! raw=$(codebase mr list ${CODEBASE_REPO_ARG[@]+"${CODEBASE_REPO_ARG[@]}"} --source-branch "$branch" --target-branch "$target_branch" --status open --verbose); then
+    printf '{"status":"error","error":"codebase mr list failed"}\n'
+    return 0
+  fi
+  if ! codebase_json_mr_normalize_list <<<"$raw"; then
+    printf '{"status":"error","error":"codebase mr list returned invalid JSON"}\n'
+    return 0
+  fi
+}
+
+mr_number_from_envelope() {
+  codebase_json_mr_field number <<<"$1"
+}
+
+mr_state_from_envelope() {
+  codebase_json_mr_field state <<<"$1"
+}
+
+mr_description_from_envelope() {
+  codebase_json_mr_field description <<<"$1"
+}
+
+mr_read_current_branch() {
+  # MR list/get/create/edit is the only Codebase operation family whose CLI
+  # transport differs by actor. Issue operations stay on bytedcli codebase.
+  case "$ACTOR" in
+    human) bytedcli --json codebase mr get ${BYTEDCLI_REPO_ARG[@]+"${BYTEDCLI_REPO_ARG[@]}"} ;;
+    agent) codebase_mr_for_branch ;;
+  esac
+}
+
+mr_create_current_branch() {
+  case "$ACTOR" in
+    human)
+      # shellcheck disable=SC2086
+      bytedcli codebase mr create \
+        ${BYTEDCLI_REPO_ARG[@]+"${BYTEDCLI_REPO_ARG[@]}"} \
+        ${BASE:+--base "$BASE"} \
+        --head "$branch" \
+        --title "$TITLE" \
+        $DRAFT_FLAG
+      ;;
+    agent)
+      codebase_actor_configure_app_env
+      create_args=(mr create)
+      [ -n "$REPO" ] && create_args+=(-R "$REPO")
+      create_args+=(--source "$branch")
+      create_args+=(--target "$target_branch")
+      create_args+=(--title "$TITLE")
+      [ -n "$DRAFT_FLAG" ] && create_args+=(--draft)
+      codebase "${create_args[@]}"
+      ;;
+  esac
+}
+
+mr_update_current() {
+  local number="$1"
+  shift
+  case "$ACTOR" in
+    human) bytedcli codebase mr update --number "$number" "$@" ${BYTEDCLI_REPO_ARG[@]+"${BYTEDCLI_REPO_ARG[@]}"} ;;
+    agent)
+      codebase_actor_configure_app_env
+      update_args=(mr edit -N "$number")
+      [ -n "$REPO" ] && update_args+=(-R "$REPO")
+      codebase "${update_args[@]}" "$@"
+      ;;
+  esac
+}
+
+issue_status() {
+  local n="$1"
+  bytedcli --json codebase issue get "$n" ${BYTEDCLI_REPO_ARG[@]+"${BYTEDCLI_REPO_ARG[@]}"} 2>/dev/null | codebase_json_issue_status 2>/dev/null || true
+}
+
+issue_mark_in_progress() {
+  local n="$1"
+  bytedcli --json codebase issue update "$n" ${BYTEDCLI_REPO_ARG[@]+"${BYTEDCLI_REPO_ARG[@]}"} --status in_progress
+}
+
+branch=$(git rev-parse --abbrev-ref HEAD)
+case "$branch" in
+  HEAD)
+    echo "error: detached HEAD; check out a feature branch first" >&2
+    exit 2
+    ;;
+  release|main|master)
+    echo "error: refusing to open MR from protected branch '$branch'" >&2
+    echo "       check out a feature branch and try again" >&2
+    exit 2
+    ;;
+esac
+
+if [ "$BODY_PROVIDED" -eq 1 ]; then
+  if [ "$BODY_STDIN" -eq 1 ]; then
+    body=$(cat)
+  else
+    body=$(cat "$BODY_FILE")
+  fi
+
+  for section in "## 变更说明" "## Docs as Code" "## 测试" "## Reviewer 关注点"; do
+    if ! grep -qF "$section" <<<"$body"; then
+      echo "error: MR body is missing required section: $section" >&2
+      exit 2
+    fi
+  done
+  for placeholder in \
+    '<!-- 用简洁 bullet 分点说明这个 MR 做了什么，以及为什么；不要写成一整段长段落 -->'; do
+    if grep -qF "$placeholder" <<<"$body"; then
+      echo "error: MR body still contains the default template placeholder" >&2
+      exit 2
+    fi
+  done
+  _desc_check_tmp=$(mktemp)
+  printf '%s\n' "$body" >"$_desc_check_tmp"
+  if ! bash scripts/check-mr-desc.sh --description-file "$_desc_check_tmp"; then
+    rm -f "$_desc_check_tmp"
+    exit 2
+  fi
+  rm -f "$_desc_check_tmp"
+fi
+target_branch="${BASE:-release}"
+
+closing_issue_numbers() {
+  local base range_base bodies kw
+  base="origin/${BASE:-release}"
+  range_base=$(git merge-base "$base" HEAD 2>/dev/null || true)
+  [ -n "$range_base" ] || return 0
+  bodies=$(git log --format=%B "$range_base"..HEAD 2>/dev/null || true)
+  [ -n "$bodies" ] || return 0
+  kw='(close[sd]?|fix(e[sd])?|resolve[sd]?)'
+  printf '%s\n' "$bodies" \
+    | grep -oiE "${kw}:?[[:space:]]+#[0-9]+([[:space:]]*(,|and)[[:space:]]*#[0-9]+)*" \
+    | grep -oE '#[0-9]+' | grep -oE '[0-9]+' | sort -u || true
+}
+
+has_closing_issue_ref_in_body() {
+  local n="$1"
+  local kw='(close[sd]?|fix(e[sd])?|resolve[sd]?)'
+  printf '%s\n' "$body" \
+    | grep -oiE "${kw}:?[[:space:]]+#[0-9]+([[:space:]]*(,|and)[[:space:]]*#[0-9]+)*" \
+    | grep -oE '#[0-9]+' | grep -oE '[0-9]+' | grep -qx "$n"
+}
+
+closing_refs=$(closing_issue_numbers)
+if [ "$BODY_PROVIDED" -eq 1 ] && [ -n "$closing_refs" ]; then
+  missing_refs=()
+  for n in $closing_refs; do
+    if ! has_closing_issue_ref_in_body "$n"; then
+      missing_refs+=("#$n")
+    fi
+  done
+  if [ "${#missing_refs[@]}" -gt 0 ]; then
+    echo "error: MR body is missing closing issue reference(s) from commit trailer(s): ${missing_refs[*]}" >&2
+    echo "hint: keep the corresponding Closes/Fixes/Resolves reference in the model-written MR description" >&2
+    exit 2
+  fi
+fi
+
+SENTINEL='<!-- generated by scripts/open-mr.sh; remove this marker to keep manual edits across re-runs -->'
+LEGACY_SENTINEL='<!-- generated by scripts/fill-mr-desc.sh; remove this marker to keep manual edits across re-runs -->'
+description=""
+if [ "$BODY_PROVIDED" -eq 1 ]; then
+  description=$(cat <<__OPEN_MR_DESC_BODY__
+${SENTINEL}
+
+${body}
+__OPEN_MR_DESC_BODY__
+)
+fi
+
+# Push -u to origin when upstream is unset OR points to a different branch on
+# origin (a common artifact of `git checkout -b feat/foo origin/release`, which
+# makes @{u} resolve to `origin/release` even though `origin/feat/foo` doesn't
+# exist yet). We want `origin/$branch` as upstream so `bytedcli mr create
+# --head $branch` resolves a real remote ref. If upstream points to a remote
+# that isn't `origin` (e.g. fork workflow with `upstream/<branch>`), refuse:
+# silently retargeting someone else's tracking remote is a footgun -- let the
+# user decide.
+upstream=$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null || true)
+upstream_remote=${upstream%%/*}
+if [ -n "$upstream" ] && [ "$upstream_remote" != "origin" ]; then
+  echo "error: branch '$branch' tracks '$upstream' (remote: $upstream_remote), not origin" >&2
+  echo "       refusing to auto-retarget; push to origin manually or re-set upstream:" >&2
+  echo "         git push -u origin $branch" >&2
+  exit 2
+fi
+if [ "$upstream" != "origin/$branch" ]; then
+  if [ "$DRY_RUN" -eq 1 ]; then
+    echo "[dry-run] would run: git push -u origin $branch  (upstream is currently '${upstream:-<unset>}')"
+  else
+    echo "==> upstream is '${upstream:-<unset>}', not 'origin/$branch'; running: git push -u origin $branch"
+    git push -u origin "$branch"
+  fi
+fi
+
+# Capture CLI stderr separately so noisy runtime warnings don't drown the real
+# auth / not-found message on failures.
+_stderr_tmp=$(mktemp)
+trap 'rm -f "$_stderr_tmp"' EXIT INT TERM
+
+# "MR not found for this branch" is a normal pre-create state, not a failure.
+# Any other error mode (auth / network / permission) -- replay the captured
+# stderr (minus the Node warning) and exit.
+mr_json=$(mr_read_current_branch 2>"$_stderr_tmp") || true
+mr_status=$(codebase_json_mr_field status <<<"${mr_json:-}" 2>/dev/null || true)
+existing_number=""
+created_by_this_run=0
+if [ "$mr_status" = "success" ]; then
+  existing_number=$(mr_number_from_envelope "$mr_json")
+  # merged/closed MRs share branch name but are not reusable -- a fresh MR is
+  # needed for any new work pushed to the same branch (e.g. follow-up commits
+  # after a squash-merge cleared the remote branch and we re-created it).
+  mr_state=$(mr_state_from_envelope "$mr_json")
+  case "$mr_state" in
+    merged|closed)
+      echo "==> MR !${existing_number} for branch '$branch' is ${mr_state}; treating branch as fresh"
+      existing_number=""
+      ;;
+  esac
+elif [ -n "$mr_json" ]; then
+  # bytedcli returned a JSON envelope but status != success. Distinguish
+  # "no MR exists for this branch yet" (acceptable) from real auth/network
+  # failures by inspecting the error message.
+  err_msg=$(codebase_json_mr_field error <<<"$mr_json" 2>/dev/null || true)
+  case "$err_msg" in
+    *"no MR"*|*"not found"*|*"NotFound"*|*"NoSuchMergeRequest"*) : ;;  # expected pre-create
+    *)
+      echo "Codebase MR lookup failed:" >&2
+      grep -v 'ExperimentalWarning' "$_stderr_tmp" >&2 || true
+      [ -n "$err_msg" ] && echo "  $err_msg" >&2
+      echo "check Codebase authentication and pass -R/--repo when origin cannot be inferred" >&2
+      exit 1
+      ;;
+  esac
+fi
+
+if [ -n "$existing_number" ]; then
+  echo "==> MR !$existing_number already exists for branch '$branch'; skipping create"
+else
+  if [ -z "$TITLE" ]; then
+    echo "error: no MR exists for branch '$branch' yet -- --title is required to create one" >&2
+    usage >&2
+    exit 2
+  fi
+  if [ "$DRY_RUN" -eq 1 ]; then
+    case "$ACTOR" in
+      human) echo "[dry-run] would run: bytedcli codebase mr create${REPO:+ -R $REPO}${BASE:+ --base $BASE} --head $branch --title \"$TITLE\" ${DRAFT_FLAG}" ;;
+      agent) echo "[dry-run] would run: codebase mr create${REPO:+ -R $REPO} --source $branch --target $target_branch --title \"$TITLE\" ${DRAFT_FLAG}" ;;
+    esac
+  else
+    echo "==> creating MR via $ACTOR Codebase CLI (title only)"
+    mr_create_current_branch
+    created_by_this_run=1
+  fi
+fi
+
+if [ "$created_by_this_run" -eq 1 ] && [ "$BODY_PROVIDED" -eq 0 ]; then
+  echo "==> no MR body provided; description left as the default template"
+  if [ -n "$closing_refs" ]; then
+    echo "warning: closing issue refs found in commits; add them to the MR description manually to keep Codebase links" >&2
+  fi
+  exit 0
+fi
+
+# Advance issues this branch references. Codebase auto-links `#N` mentions from
+# the MR description, so the model-written body should keep any intended issue
+# references from the drafting context. There is no relate API in bytedcli; what
+# we can do here is move a `Closes #N` / `Fixes #N` issue to in_progress now
+# that an MR is open for it. `Refs #N` is only surfaced.
+progress_referenced_issues() {
+  # Scan commit bodies unique to this branch vs the target base.
+  local base range_base bodies closes refs n
+  base="origin/${BASE:-release}"
+  range_base=$(git merge-base "$base" HEAD 2>/dev/null || true)
+  [ -n "$range_base" ] || return 0
+  bodies=$(git log --format=%B "$range_base"..HEAD 2>/dev/null || true)
+  [ -n "$bodies" ] || return 0
+
+  # Closing keywords -> in_progress; bare Refs -> surface only. Case-insensitive.
+  # Capture comma/and-separated lists too, e.g. `Closes #12, #13 and #14`.
+  # Tolerate an optional colon and any whitespace: `Closes #1`, `Closes: #1`,
+  # `Fixes:  #1`, plus comma/and-separated lists.
+  local kw='(close[sd]?|fix(e[sd])?|resolve[sd]?)'
+  closes=$(printf '%s\n' "$bodies" \
+    | grep -oiE "${kw}:?[[:space:]]+#[0-9]+([[:space:]]*(,|and)[[:space:]]*#[0-9]+)*" \
+    | grep -oE '#[0-9]+' | grep -oE '[0-9]+' | sort -u || true)
+  refs=$(printf '%s\n' "$bodies" \
+    | grep -oiE "refs?:?[[:space:]]+#[0-9]+([[:space:]]*(,|and)[[:space:]]*#[0-9]+)*" \
+    | grep -oE '#[0-9]+' | grep -oE '[0-9]+' | sort -u || true)
+
+  [ -n "$refs" ] && echo "==> referenced issues (will link via MR description): $(echo "$refs" | paste -sd' ' -)"
+  [ -n "$closes" ] || return 0
+
+  # Own temp file (created only on the path that uses it, so early returns
+  # above don't leak it); cleaned at the end of the function.
+  local _err; _err=$(mktemp)
+  for n in $closes; do
+    # Only advance forward from an un-started state -- never regress a `done` /
+    # `canceled` / already-`in_progress` issue when a commit references an old
+    # number or `make open-mr` is re-run.
+    local cur
+    cur=$(issue_status "$n")
+    case "$cur" in
+      backlog|todo) : ;;
+      "") echo "warning: could not read issue #$n status; leaving it unchanged" >&2; continue ;;
+      *) echo "==> issue #$n is '$cur'; not auto-advancing"; continue ;;
+    esac
+    if [ "$DRY_RUN" -eq 1 ]; then
+      echo "[dry-run] would run: bytedcli codebase issue update $n${REPO:+ -R $REPO} --status in_progress (current: $cur)"
+      continue
+    fi
+    echo "==> moving referenced issue #$n ($cur -> in_progress)"
+    if ! issue_mark_in_progress "$n" >/dev/null 2>"$_err"; then
+      # Non-fatal: opening the MR already succeeded; a bad/closed issue ref
+      # must not fail the whole flow.
+      echo "warning: could not update issue #$n:" >&2
+      grep -v 'ExperimentalWarning' "$_err" >&2 || true
+    fi
+  done
+  rm -f "$_err"
+}
+
+if [ -z "$existing_number" ] && [ "$DRY_RUN" -ne 1 ]; then
+  mr_json=$(mr_read_current_branch 2>"$_stderr_tmp") || true
+  mr_status=$(codebase_json_mr_field status <<<"${mr_json:-}" 2>/dev/null || true)
+  if [ "$mr_status" != "success" ]; then
+    echo "error: MR was created but could not be read back for description update" >&2
+    grep -v 'ExperimentalWarning' "$_stderr_tmp" >&2 || true
+    exit 1
+  fi
+  existing_number=$(mr_number_from_envelope "$mr_json")
+fi
+
+mr_number="$existing_number"
+if [ -z "$mr_number" ] && [ "$DRY_RUN" -ne 1 ]; then
+  echo "error: could not determine MR number for description update" >&2
+  exit 1
+fi
+
+if [ "$BODY_PROVIDED" -eq 0 ]; then
+  if [ "$DRY_RUN" -eq 1 ]; then
+    if [ -n "$mr_number" ] && [ -n "$TITLE" ]; then
+      echo "[dry-run] would update MR !${mr_number} title only"
+      echo "[dry-run] new title: $TITLE"
+    elif [ -n "$mr_number" ]; then
+      echo "[dry-run] MR !${mr_number} already exists; no body provided, description would remain unchanged"
+    else
+      echo "[dry-run] would leave the newly created MR description as the default template"
+    fi
+    exit 0
+  fi
+  if [ "$created_by_this_run" -ne 1 ] && [ -n "$mr_number" ] && [ -n "$TITLE" ] && [ -n "$existing_number" ]; then
+    echo "==> updating MR !${mr_number} title only; description left unchanged for manual editing"
+    mr_update_current "$mr_number" --title "$TITLE"
+  else
+    echo "==> no MR body provided; description left as the default/current template for manual editing"
+  fi
+  if [ -n "$closing_refs" ]; then
+    echo "warning: closing issue refs found in commits; add them to the MR description manually to keep Codebase links" >&2
+  fi
+  exit 0
+fi
+
+if [ -n "$mr_number" ]; then
+  if [ -n "${mr_json:-}" ]; then
+    existing_desc=$(mr_description_from_envelope "$mr_json")
+  else
+    existing_desc=""
+  fi
+  if [ "$created_by_this_run" -ne 1 ] \
+    && [ -n "$existing_desc" ] && [ "$FORCE" -ne 1 ] \
+    && ! grep -qF "$SENTINEL" <<<"$existing_desc" \
+    && ! grep -qF "$LEGACY_SENTINEL" <<<"$existing_desc"; then
+    echo "MR !${mr_number} already has a hand-written description (no script sentinel found)." >&2
+    echo "Pass --force to overwrite, or remove the description first." >&2
+    exit 1
+  fi
+fi
+
+update_fields=()
+[ -n "$TITLE" ] && update_fields+=(--title "$TITLE")
+update_fields+=(--body "$description")
+
+if [ "$DRY_RUN" -eq 1 ]; then
+  if [ -n "$mr_number" ]; then
+    echo "[dry-run] would update MR !${mr_number} description${TITLE:+ and title}"
+    [ -n "$TITLE" ] && echo "[dry-run] new title: $TITLE"
+  else
+    echo "[dry-run] would update the newly created MR body after create"
+  fi
+  echo "---"
+  printf '%s\n' "$description"
+  progress_referenced_issues
+  exit 0
+fi
+
+echo "==> updating MR !${mr_number} description${TITLE:+ and title}"
+mr_update_current "$mr_number" "${update_fields[@]}"
+progress_referenced_issues
+
+if [ "$ACTOR" = "agent" ] \
+  && [ "${CODING_MR_AUTO_RERUN_CHECKS:-1}" != "0" ] \
+  && [ -x scripts/rerun-mr-checks-as-human.sh ]; then
+  echo "==> best-effort rerun of failed MR checks via bytedcli human/PAT identity"
+  if [ -n "$REPO" ]; then
+    scripts/rerun-mr-checks-as-human.sh --mr "$mr_number" -R "$REPO" || true
+  else
+    scripts/rerun-mr-checks-as-human.sh --mr "$mr_number" || true
+  fi
+fi

package/templates/scripts/regen-agent-md.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# Regenerate the auto-managed skill registry table in .agents/skills/REGISTRY.md
+# from each .agents/skills/coding-*/SKILL.md frontmatter (`name` + `description`).
+#
+# REGISTRY.md holds the verbose per-skill descriptions + lifecycle cadence; the
+# path→skill routing table that every agent reads on each edit stays inline in
+# AGENTS.md §Skill Router (Codex / Antigravity / Trae read it natively, the
+# Claude Code hook + Cursor mirror duplicate it). Keeping the descriptions in
+# REGISTRY.md keeps the always-loaded AGENTS.md lean while still syncing one
+# source without per-tool file duplication.
+#
+# Modes:
+#   (no flag) : rewrite the target in place between markers
+#   --check   : dry-run; exit 1 with diff if the target is out of sync
+#
+# The replaced block sits between these exact-line markers in the target:
+#   <!-- skills:start (auto-generated by make regen-agent-md) -->
+#   <!-- skills:end -->
+#
+# Anything outside the markers is preserved verbatim.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# shellcheck source=scripts/lib/skill-frontmatter.sh
+. scripts/lib/skill-frontmatter.sh
+
+TARGET=".agents/skills/REGISTRY.md"
+START_MARKER='<!-- skills:start (auto-generated by make regen-agent-md) -->'
+END_MARKER='<!-- skills:end -->'
+
+mode="write"
+case "${1:-}" in
+    "" ) ;;
+    --check ) mode="check" ;;
+    -h|--help )
+        cat <<EOF
+Usage: $0 [--check]
+
+  (no flag)  rewrite $TARGET in place between skill registry markers
+  --check    exit 1 with diff if $TARGET is out of sync (for CI / pre-commit)
+EOF
+        exit 0
+        ;;
+    * )
+        echo "error: unknown flag: $1" >&2
+        exit 2
+        ;;
+esac
+
+if [[ ! -f "$TARGET" ]]; then
+    echo "error: $TARGET not found" >&2
+    exit 2
+fi
+
+# AGENTS.md is the always-loaded routing layer for every agent CLI; keep it
+# lean. Enforced in --check mode, which both the pre-commit `check-agent-md`
+# hook and `make check-agent-md` invoke.
+MAX_AGENT_MD_LINES=200
+if [[ "$mode" == "check" && -f AGENTS.md ]]; then
+    agent_md_lines=$(wc -l < AGENTS.md | tr -d ' ')
+    if (( agent_md_lines > MAX_AGENT_MD_LINES )); then
+        echo "[FAIL] AGENTS.md is ${agent_md_lines} lines (max ${MAX_AGENT_MD_LINES}) — it is the always-loaded routing layer; move detail into a skill instead" >&2
+        exit 1
+    fi
+fi
+
+# Marker presence is mandatory; do not silently insert markers into a file
+# that someone has intentionally stripped.
+if ! grep -qxF "$START_MARKER" "$TARGET"; then
+    echo "error: $TARGET missing start marker line:" >&2
+    echo "  $START_MARKER" >&2
+    exit 2
+fi
+if ! grep -qxF "$END_MARKER" "$TARGET"; then
+    echo "error: $TARGET missing end marker line:" >&2
+    echo "  $END_MARKER" >&2
+    exit 2
+fi
+
+# ── Build the regenerated block from frontmatter ─────────────────────────
+build_block() {
+    printf '%s\n\n' "$START_MARKER"
+    printf '| Skill | When to use |\n'
+    printf '|---|---|\n'
+
+    local skill_md name desc warned=0
+    for skill_md in "$SKILLS_ROOT"/coding-*/SKILL.md; do
+        [[ -f "$skill_md" ]] || continue
+        name=$(extract_field "$skill_md" name)
+        desc=$(extract_field "$skill_md" description)
+        if [[ -z "$name" ]]; then
+            echo "warn: $skill_md missing 'name' in frontmatter, skipping" >&2
+            warned=1
+            continue
+        fi
+        if [[ -z "$desc" ]]; then
+            echo "warn: $skill_md missing 'description' in frontmatter, skipping" >&2
+            warned=1
+            continue
+        fi
+        if [[ "$desc" == *'|'* ]]; then
+            # A literal pipe would break the markdown table. Don't try to
+            # auto-escape — flag it so the SKILL.md author fixes it.
+            echo "warn: $skill_md description contains '|'; this will break the table. Replace with '/' or HTML entity." >&2
+            warned=1
+        fi
+        printf '| `%s` | %s |\n' "$name" "$desc"
+    done
+
+    printf '%s\n' "$END_MARKER"
+    return $warned
+}
+
+# `build_block` returns 1 on soft warnings (missing frontmatter, pipe in
+# description). The `|| build_status=$?` absorbs the non-zero return so
+# `set -e` doesn't kill us before we splice + report — otherwise the
+# warning path is dead code.
+build_status=0
+block=$(build_block) || build_status=$?
+
+# ── Splice the new block into the target ────────────────────────────────
+# Match marker lines exactly (full-line equality) to avoid accidental matches
+# inside narrative paragraphs. BSD awk rejects newlines in -v values, so we
+# stream the file in three pieces and inject `block` via printf in between.
+tmp_new=$(mktemp -t regen-agent-md.XXXXXX)
+trap 'rm -f "$tmp_new"' EXIT
+
+{
+    awk -v marker="$START_MARKER" '$0 == marker { exit } { print }' "$TARGET"
+    printf '%s\n' "$block"
+    awk -v marker="$END_MARKER" 'found { print } $0 == marker { found = 1 }' "$TARGET"
+} > "$tmp_new"
+
+if cmp -s "$TARGET" "$tmp_new"; then
+    echo "[OK] $TARGET skill registry already up to date"
+    exit "$build_status"
+fi
+
+if [[ "$mode" == "check" ]]; then
+    echo "[FAIL] $TARGET skill registry is out of sync. Run: make regen-agent-md" >&2
+    diff -u "$TARGET" "$tmp_new" >&2 || true
+    exit 1
+fi
+
+cp "$tmp_new" "$TARGET"
+echo "[OK] rewrote skill registry in $TARGET"
+exit "$build_status"