@cxi-lmai/ci-agent-platform 3.0.1 → 3.1.1

package/payload/ci-templates/scripts/coverage-ratchet.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Opt-in coverage gate. Reads the configured coverage report, compares it with
+# the target branch's latest successful pipeline, and sends coverage drops on
+# wip merge requests into the existing test-fix loop.
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib/pipeline-common.sh
+source "$SCRIPT_DIR/lib/pipeline-common.sh"
+pipe_defaults
+
+coverage_from_jacoco() {
+  local covered missed
+  if ! covered=$(xmllint --xpath 'string(//report/counter[@type="INSTRUCTION"]/@covered)' \
+    "$PIPE_COVERAGE_REPORT" 2>/dev/null) ||
+    ! missed=$(xmllint --xpath 'string(//report/counter[@type="INSTRUCTION"]/@missed)' \
+    "$PIPE_COVERAGE_REPORT" 2>/dev/null); then
+    echo "ERROR: unable to parse JaCoCo instruction coverage from: $PIPE_COVERAGE_REPORT" >&2
+    return 1
+  fi
+
+  if [[ "$covered" =~ ^[0-9]+$ ]] && [[ "$missed" =~ ^[0-9]+$ ]] && \
+    [ "$((covered + missed))" -gt 0 ]; then
+    printf '%s\n' "$((covered * 100 / (covered + missed)))"
+  else
+    echo "ERROR: unable to parse JaCoCo instruction coverage from: $PIPE_COVERAGE_REPORT" >&2
+    return 1
+  fi
+}
+
+case "$PIPE_COVERAGE_REPORT_KIND" in
+  jacoco) ;;
+  *) echo "ERROR: unsupported coverage report kind: $PIPE_COVERAGE_REPORT_KIND" >&2; exit 1 ;;
+esac
+
+[ -z "${PIPE_MR_IID:-}" ] && exit 0
+
+if [ -z "$PIPE_COVERAGE_REPORT" ] || [ ! -f "$PIPE_COVERAGE_REPORT" ]; then
+  echo "Coverage ratchet inactive: coverage report is not available: ${PIPE_COVERAGE_REPORT:-<unset>}"
+  exit 0
+fi
+
+command -v xmllint >/dev/null 2>&1 || {
+  echo "ERROR: xmllint is required to parse PIPE_COVERAGE_REPORT" >&2
+  exit 1
+}
+
+CURRENT_COV=$(coverage_from_jacoco)
+
+if [ "$PIPE_COVERAGE_RATCHET" = "1" ] && [ -z "$PIPE_COVERAGE_SIGNAL" ]; then
+  echo "ERROR: PIPE_COVERAGE_SIGNAL must be set when PIPE_COVERAGE_RATCHET=1" >&2
+  exit 1
+fi
+
+BASELINE=$(platform_latest_success_coverage "$PIPE_TARGET_BRANCH" 2>/dev/null || true)
+BASELINE=${BASELINE%%.*}
+[[ "$BASELINE" =~ ^[0-9]+$ ]] || BASELINE=0
+
+echo "Total coverage: ${CURRENT_COV}%"
+echo "Coverage: current=${CURRENT_COV}% baseline=${BASELINE}%"
+
+if [ "$CURRENT_COV" -lt "$BASELINE" ]; then
+  echo "WARNING: Coverage dropped from ${BASELINE}% to ${CURRENT_COV}%"
+  COMMENT_FILE="$PIPE_CONTEXT_DIR/coverage-ratchet.md"
+  printf '**Coverage dropped** from %s%% to %s%%. Please check whether new code is missing tests.\n' \
+    "$BASELINE" "$CURRENT_COV" > "$COMMENT_FILE"
+  platform_post_comment_file "$COMMENT_FILE" || true
+
+  LABELS=$(platform_mr_labels)
+  case ",$LABELS," in
+    *",$PIPE_LABEL_WIP,"*)
+      printf 'COVERAGE_DROP:%s:%s\n' "$BASELINE" "$CURRENT_COV" > "$PIPE_COVERAGE_SIGNAL"
+      echo "Coverage dropped on $PIPE_LABEL_WIP MR/PR — exiting 1 to trigger test-fix"
+      exit 1
+      ;;
+  esac
+fi

package/payload/ci-templates/scripts/cve-fix.sh

@@ -0,0 +1,246 @@
+#!/bin/bash
+# Runner for the opt-in CVE remediation job. A project-local scanner supplies
+# HIGH/CRITICAL identifiers in PIPE_CVE_LIST; this runner scopes the coder,
+# verifies its commit and compile result, and alone owns rebase/push/comments.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib/pipeline-common.sh
+source "$SCRIPT_DIR/lib/pipeline-common.sh"
+pipe_defaults
+
+CONTEXT_FILE="$PIPE_CONTEXT_DIR/cve-fix-context.md"
+CVE_LIST_FILE="$PIPE_CONTEXT_DIR/cve-fix-list.txt"
+MANIFEST_FILE="$PIPE_CONTEXT_DIR/cve-fix-manifest.txt"
+CVE_ENV="$PIPE_CONTEXT_DIR/cve-fix.env"
+COMMENT_FILE="$PIPE_CONTEXT_DIR/cve-fix-comment.md"
+
+# The scanner controls both selection and severity filtering. Bound its output
+# before it reaches a context or comment, and never forward it in argv/env.
+head -c 8000 <<< "${PIPE_CVE_LIST:-}" > "$CVE_LIST_FILE"
+# A cap can cut the final list entry mid-line. Add only a record terminator
+# before filtering/counting; the caller-provided content remains bounded.
+printf '\n' >> "$CVE_LIST_FILE"
+sed -i '/^[[:space:]]*$/d' "$CVE_LIST_FILE"
+CVE_COUNT=$(awk 'NF { count++ } END { print count + 0 }' "$CVE_LIST_FILE")
+
+write_marker() {
+  # Marker values are canonical runner output. Never source model-written data.
+  printf 'CVE_FIX_APPLIED=%s\nCVE_COMPILED=%s\nCVE_COUNT=%s\nCVE_MANUAL_REQUIRED=%s\n' \
+    "$1" "$2" "$CVE_COUNT" "$3" > "$CVE_ENV"
+}
+
+post_comment() {
+  # Posts the complete, bounded body already written to $COMMENT_FILE.
+  platform_post_comment_file "$COMMENT_FILE" || pipe_log "Could not post CVE remediation comment"
+}
+
+post_manual_comment() {
+  # $1 is the short manual-action explanation. The list is bounded above.
+  {
+    printf '**Automated CVE remediation requires manual action.**\n\n%s\n' "$1"
+    if [ -s "$CVE_LIST_FILE" ]; then
+      printf '\nAffected HIGH/CRITICAL vulnerability identifiers:\n'
+      sed 's/^/- /' "$CVE_LIST_FILE"
+    fi
+  } > "$COMMENT_FILE"
+  post_comment
+}
+
+count_matching_commits() {
+  local count=0 subject
+  while IFS= read -r subject; do
+    [ "$subject" = "$PIPE_COMMIT_CVEFIX" ] && count=$((count + 1))
+  done < <(git log "origin/$PIPE_TARGET_BRANCH..HEAD" --format='%s' 2>/dev/null)
+  printf '%s\n' "$count"
+}
+
+marker_is_valid() {
+  local line applied=0 compiled=0 count=0 manual=0
+  [ -f "$CVE_ENV" ] || return 1
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+      CVE_FIX_APPLIED=0|CVE_FIX_APPLIED=1) applied=$((applied + 1)) ;;
+      CVE_COMPILED=0|CVE_COMPILED=1) compiled=$((compiled + 1)) ;;
+      CVE_MANUAL_REQUIRED=0|CVE_MANUAL_REQUIRED=1) manual=$((manual + 1)) ;;
+      CVE_COUNT=*)
+        [[ "$line" =~ ^CVE_COUNT=[0-9]+$ ]] || return 1
+        count=$((count + 1))
+        ;;
+      *) return 1 ;;
+    esac
+  done < "$CVE_ENV"
+  [ "$applied" -eq 1 ] && [ "$compiled" -eq 1 ] && [ "$count" -eq 1 ] && [ "$manual" -eq 1 ]
+}
+
+marker_value() {
+  # marker_is_valid has already limited this to a literal 0, 1, or decimal.
+  pipe_get_env "$CVE_ENV" "$1"
+}
+
+# This job has no purpose outside a merge/pull-request pipeline. Do not attempt
+# a forge lookup that can accidentally turn a branch pipeline into a comment.
+if [ -z "${PIPE_MR_IID:-}" ]; then
+  pipe_log "No merge request/pull request context; CVE remediation is inactive"
+  exit 0
+fi
+
+# Empty scanner output is normal and must remain silent. Check it before any
+# metadata/WIP gate so enabling the optional job does not spam ordinary MRs.
+if [ "$CVE_COUNT" = "0" ]; then
+  pipe_log "No vulnerability identifiers supplied; CVE remediation is inactive"
+  write_marker 0 0 1
+  exit 0
+fi
+
+# The list was supplied by the caller and can be arbitrarily large. The only
+# bounded copy is the context file above; do not let the dispatcher inherit it.
+unset PIPE_CVE_LIST
+
+META=$(platform_mr_meta 2>/dev/null || true)
+MR_LABELS=$(jq -r '.labels // ""' <<< "$META" 2>/dev/null || true)
+META_SOURCE_BRANCH=$(jq -r '.source_branch // ""' <<< "$META" 2>/dev/null || true)
+if [ -n "$META_SOURCE_BRANCH" ]; then
+  PIPE_SOURCE_BRANCH="$META_SOURCE_BRANCH"
+  export PIPE_SOURCE_BRANCH
+fi
+if [ -z "${PIPE_SOURCE_BRANCH:-}" ]; then
+  pipe_log "MR/PR metadata has no source branch"
+  post_manual_comment "The source branch metadata is unavailable; update the dependencies manually."
+  write_marker 0 0 1
+  exit 0
+fi
+
+if ! grep -qF "$PIPE_LABEL_WIP" <<< "$MR_LABELS"; then
+  pipe_log "MR/PR is not labeled $PIPE_LABEL_WIP; requesting a manual dependency update"
+  post_manual_comment "This MR/PR is not marked for autonomous changes; update the dependencies manually."
+  write_marker 0 0 1
+  exit 0
+fi
+
+# A dependency manifest is project-relative by contract. Reject paths that
+# could point outside this checkout before using them in git or file commands.
+case "$PIPE_DEPENDENCY_MANIFEST" in
+  ''|/*|..|../*|*/..|*/../*)
+    pipe_log "Invalid project-relative dependency manifest path: $PIPE_DEPENDENCY_MANIFEST"
+    post_manual_comment "The configured dependency manifest path is invalid; update the dependencies manually."
+    write_marker 0 0 1
+    exit 0
+    ;;
+esac
+
+pipe_git_identity
+pipe_checkout_source
+if ! git rev-parse --verify "origin/$PIPE_SOURCE_BRANCH" >/dev/null 2>&1 \
+  || [ "$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)" != "$PIPE_SOURCE_BRANCH" ]; then
+  pipe_log "Unable to check out source branch safely: $PIPE_SOURCE_BRANCH"
+  post_manual_comment "The source branch could not be checked out safely; update the dependencies manually."
+  write_marker 0 0 1
+  exit 0
+fi
+
+EXISTING_FIXES=$(count_matching_commits)
+if [ "$EXISTING_FIXES" -ge "$PIPE_FIX_LOOP_CAP" ]; then
+  pipe_log "CVE remediation reached its commit budget ($EXISTING_FIXES/$PIPE_FIX_LOOP_CAP)"
+  post_manual_comment "The CVE remediation commit budget is exhausted; update the dependencies manually."
+  write_marker 0 0 1
+  exit 0
+fi
+
+if [ ! -f "$PIPE_DEPENDENCY_MANIFEST" ]; then
+  pipe_log "Dependency manifest is missing: $PIPE_DEPENDENCY_MANIFEST"
+  post_manual_comment "Dependency manifest is missing: \`$PIPE_DEPENDENCY_MANIFEST\`. Update the dependencies manually."
+  write_marker 0 0 1
+  exit 0
+fi
+head -c 8000 "$PIPE_DEPENDENCY_MANIFEST" > "$MANIFEST_FILE"
+REMAINING_BUDGET=$((PIPE_FIX_LOOP_CAP - EXISTING_FIXES))
+rm -f "$CVE_ENV"
+{
+  printf '# CVE remediation context\n\n'
+  printf 'Mode: apply\n'
+  printf 'Vulnerability List File: %s\n' "$CVE_LIST_FILE"
+  printf 'Dependency Manifest Path: %s\n' "$PIPE_DEPENDENCY_MANIFEST"
+  printf 'Dependency Manifest Content File: %s\n' "$MANIFEST_FILE"
+  printf 'Compile Command: %s\n' "$PIPE_COMPILE_CMD"
+  printf 'Commit Subject: %s\n' "$PIPE_COMMIT_CVEFIX"
+  printf 'Source Branch: %s\n' "$PIPE_SOURCE_BRANCH"
+  printf 'Target Branch: %s\n' "$PIPE_TARGET_BRANCH"
+  printf 'Suppression Path: %s\n' "$PIPE_CVE_SUPPRESSIONS"
+  printf 'Remaining Commit Budget: %s\n' "$REMAINING_BUDGET"
+  printf 'Marker File: %s\n' "$CVE_ENV"
+} > "$CONTEXT_FILE"
+
+# The skill decides dependency versions. This is the same code-writing policy
+# as other runners; it receives no shell-built remediation prompt.
+PRE_AGENT_SHA=$(git rev-parse HEAD)
+pipe_run_agent cve-fix "/cve-fix" "Agent,Read,Write,Edit,Glob,Grep,Bash" "$PIPE_MODEL_CODE" < /dev/null
+POST_AGENT_SHA=$(git rev-parse HEAD)
+NEW_FIXES=$(count_matching_commits)
+RANGE_COMMITS=$(git rev-list --count "$PRE_AGENT_SHA..$POST_AGENT_SHA" 2>/dev/null || echo 0)
+RANGE_HAS_DIFF=false
+if ! git diff --quiet "$PRE_AGENT_SHA..$POST_AGENT_SHA" 2>/dev/null; then
+  RANGE_HAS_DIFF=true
+fi
+RANGE_MANIFEST_ONLY=true
+while IFS= read -r path; do
+  [ "$path" = "$PIPE_DEPENDENCY_MANIFEST" ] || { RANGE_MANIFEST_ONLY=false; break; }
+done < <(git diff --name-only "$PRE_AGENT_SHA..$POST_AGENT_SHA" 2>/dev/null)
+
+if ! marker_is_valid || [ "$(marker_value CVE_FIX_APPLIED)" != "1" ] \
+  || [ "$(marker_value CVE_COMPILED)" != "1" ] || [ "$(marker_value CVE_MANUAL_REQUIRED)" != "0" ] \
+  || [ "$NEW_FIXES" -ne $((EXISTING_FIXES + 1)) ] || [ "$RANGE_COMMITS" != "1" ] \
+  || [ "$(git log -1 --format='%s' 2>/dev/null)" != "$PIPE_COMMIT_CVEFIX" ] \
+  || [ "$RANGE_HAS_DIFF" != true ] || [ "$RANGE_MANIFEST_ONLY" != true ]; then
+  # This range and its dirty tracked files belong to the agent. Restore the
+  # checked-out remote tip; do not carry unverified work into a later rebase.
+  git reset --hard "$PRE_AGENT_SHA" >/dev/null 2>&1 || git checkout -- . || true
+  pipe_failure_log_notice_files "CVE remediation" "update the listed dependencies manually" "$PIPE_AGENT_STDERR" >&2
+  {
+    pipe_failure_notice_files "CVE remediation" "update the listed dependencies manually" "$PIPE_AGENT_STDERR"
+    printf '\n'
+    if [ -s "$CVE_LIST_FILE" ]; then
+      printf 'Affected HIGH/CRITICAL vulnerability identifiers:\n'
+      sed 's/^/- /' "$CVE_LIST_FILE"
+    fi
+    printf '\nThe coder made no verified remediation commit, so manual dependency update is required.\n'
+  } > "$COMMENT_FILE"
+  post_comment
+  write_marker 0 0 1
+  exit 0
+fi
+
+# The accepted commit is authoritative. Reset index and worktree to it so
+# compile/rebase see exactly what the runner will push; context artifacts stay
+# untracked and are therefore preserved.
+git reset --hard HEAD
+
+if [ -z "$PIPE_COMPILE_CMD" ]; then
+  pipe_log "Configured compile command is empty; refusing to push an unverified CVE remediation"
+  post_manual_comment "The configured compile command is empty, so the automated dependency update cannot be verified."
+  write_marker 1 0 1
+  exit 1
+fi
+if ! bash -c "$PIPE_COMPILE_CMD"; then
+  pipe_log "CVE remediation compile command failed; refusing to push"
+  post_manual_comment "The automated dependency update was committed locally but the compile command failed; manual review is required."
+  write_marker 1 0 1
+  exit 1
+fi
+
+if ! pipe_rebase_and_push; then
+  pipe_log "CVE remediation rebase/push failed; human work was not overwritten"
+  post_manual_comment "The automated dependency update could not be rebased and pushed safely; resolve the branch changes manually."
+  write_marker 1 1 1
+  exit 1
+fi
+
+{
+  printf '**Automated CVE remediation succeeded.**\n\n'
+  printf 'The configured dependency manifest was updated, compiled, rebased, and pushed.\n\n'
+  printf 'Remediated HIGH/CRITICAL vulnerability identifiers:\n'
+  sed 's/^/- /' "$CVE_LIST_FILE"
+} > "$COMMENT_FILE"
+post_comment
+write_marker 1 1 0
+pipe_log "Pushed verified CVE remediation commit"

package/payload/ci-templates/scripts/docs-sync.sh

@@ -0,0 +1,225 @@
+#!/bin/bash
+# Runner for the opt-in `docs-sync` job. Finds documentation gaps AND acts on
+# them in a single pass: on a wip MR/PR the skill applies the documentation
+# edits and this script commits and pushes them, on any other MR/PR the skill
+# reports the gaps and this script posts them as an advisory comment.
+#
+# The runner is mechanical: it classifies the MR/PR, computes the changed files
+# and the full diff, runs the /docs-sync skill, posts the verdict, and commits.
+# Every judgement about what needs documenting lives in the skill and in the
+# docs-sync agent it spawns.
+#
+# The diff is always base..head, never an incremental slice: a gap introduced by
+# an earlier push must still be found on a later one.
+set -e
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib/pipeline-common.sh
+source "$SCRIPT_DIR/lib/pipeline-common.sh"
+pipe_defaults
+
+DOCS_MARKER="**Automated Documentation Sync**"
+CONTEXT_FILE="$PIPE_CONTEXT_DIR/docs-sync-context.md"
+FILES_FILE="$PIPE_CONTEXT_DIR/docs-sync-files.txt"
+DIFF_FILE="$PIPE_CONTEXT_DIR/docs-sync-diff.patch"
+DOCS_ENV="$PIPE_CONTEXT_DIR/docs-sync.env"
+COMMENT_FILE="$PIPE_CONTEXT_DIR/docs-sync-comment.md"
+
+# Documentation roots the agent may edit and this script may commit. Comma
+# separated in PIPE_DOCS_ROOTS; a root is a directory or a single file.
+# The split is a bash field split, not `tr ',' '\n'` piped into `read`: that
+# pipeline emits no trailing newline, so `read` silently drops the LAST root.
+# Surrounding whitespace is trimmed per element so "docs, CLAUDE.md" works.
+DOCS_ROOTS=()
+IFS=',' read -ra DOCS_ROOTS_RAW <<< "$PIPE_DOCS_ROOTS"
+for root in "${DOCS_ROOTS_RAW[@]}"; do
+  root="${root#"${root%%[![:space:]]*}"}"
+  root="${root%"${root##*[![:space:]]}"}"
+  if [ -n "$root" ]; then
+    DOCS_ROOTS+=("$root")
+  fi
+done
+if [ "${#DOCS_ROOTS[@]}" -eq 0 ]; then
+  pipe_log "PIPE_DOCS_ROOTS is empty, nothing to sync"
+  exit 0
+fi
+
+# True when the path is one of the documentation roots or sits under one.
+docs_root_path() {
+  local root
+  for root in "${DOCS_ROOTS[@]}"; do
+    [ "$1" = "$root" ] && return 0
+    case "$1" in "$root"/*) return 0 ;; esac
+  done
+  return 1
+}
+
+# 1. Fetch MR/PR meta (token work). The source branch comes from the same read:
+#    it is what an applied documentation commit is pushed to, and the CI runtime
+#    does not always provide it.
+META=$(platform_mr_meta)
+MR_TITLE=$(echo "$META"  | jq -r '.title // ""')
+MR_LABELS=$(echo "$META" | jq -r '.labels // ""')
+META_SOURCE_BRANCH=$(echo "$META" | jq -r '.source_branch // ""')
+if [ -z "${PIPE_SOURCE_BRANCH:-}" ] && [ -n "$META_SOURCE_BRANCH" ]; then
+  PIPE_SOURCE_BRANCH="$META_SOURCE_BRANCH"
+  export PIPE_SOURCE_BRANCH
+fi
+
+# 2. Classify. Only an autonomous (wip) MR/PR gets its documentation edited;
+#    a human-authored one gets a report.
+DOCS_MODE=report
+if echo "$MR_LABELS" | grep -q "$PIPE_LABEL_WIP"; then
+  DOCS_MODE=apply
+fi
+
+# 3. Full-MR diff base. platform_compute_diff_base would hand back the previous
+#    push head on a re-run, which is the wrong scope for this job, so the base
+#    is always the merge base with the target branch.
+git fetch origin "$PIPE_TARGET_BRANCH" 2>/dev/null || true
+DIFF_BASE=$(git merge-base "origin/$PIPE_TARGET_BRANCH" "$PIPE_HEAD_SHA" 2>/dev/null || echo "origin/$PIPE_TARGET_BRANCH")
+pipe_log "mode=$DOCS_MODE diff base=$DIFF_BASE head=$PIPE_HEAD_SHA"
+
+git diff --name-only "$DIFF_BASE" "$PIPE_HEAD_SHA" > "$FILES_FILE" 2>/dev/null || : > "$FILES_FILE"
+if [ ! -s "$FILES_FILE" ]; then
+  pipe_log "No changed files in $DIFF_BASE..$PIPE_HEAD_SHA, skipping docs-sync"
+  exit 0
+fi
+
+# 4. Skip when the MR/PR only touches documentation: there is no new behaviour
+#    to document, and the author is already editing the docs.
+CODE_CHANGED=false
+while IFS= read -r file; do
+  [ -n "$file" ] || continue
+  if ! docs_root_path "$file"; then
+    CODE_CHANGED=true
+    break
+  fi
+done < "$FILES_FILE"
+if [ "$CODE_CHANGED" = "false" ]; then
+  pipe_log "Only documentation paths changed, skipping docs-sync"
+  exit 0
+fi
+
+git diff "$DIFF_BASE" "$PIPE_HEAD_SHA" > "$DIFF_FILE" 2>/dev/null || : > "$DIFF_FILE"
+
+# 5. In apply mode, check out the real source branch so the edits and the commit
+#    land on its tip. Loop guard: at most one consecutive automated docs commit
+#    per branch streak, otherwise apply -> pipeline -> apply would never settle.
+#    The guard degrades this run to report mode instead of skipping it, so the
+#    MR/PR still gets a verdict.
+if [ "$DOCS_MODE" = "apply" ]; then
+  pipe_git_identity
+  pipe_checkout_source
+  if [ "$(pipe_count_fix_commits "$PIPE_COMMIT_DOCSSYNC")" -gt 0 ]; then
+    pipe_log "Tip is already an automated docs commit, degrading to report mode"
+    DOCS_MODE=report
+  fi
+fi
+
+# 6. Write the context file the skill reads. Unbounded text (the diff, the file
+#    list) stays in its own file, never in argv or the environment.
+{
+  echo "# Documentation sync context"
+  echo
+  echo "Mode: $DOCS_MODE"
+  echo "Title: $MR_TITLE"
+  echo "Documentation roots: $PIPE_DOCS_ROOTS"
+  echo "Changed files: $FILES_FILE"
+  echo "Full diff: $DIFF_FILE"
+  echo "Diff range: $DIFF_BASE..$PIPE_HEAD_SHA"
+} > "$CONTEXT_FILE"
+
+# 7. Run the skill. It reads the context, spawns the docs-sync agent in the
+#    requested mode, writes $PIPE_RESULT_DOCSSYNC, the comment body, and the
+#    docs-sync.env marker this script reads back.
+pipe_run_agent docs-sync "/docs-sync" "Agent,Read,Write,Edit,Glob,Grep,Bash" "$PIPE_MODEL_REVIEW" < /dev/null
+
+# 8. Read the marker. DOCS_COMMENT_PATH carries the body because a comment is
+#    unbounded text. A result file written by a model can be malformed JSON, so
+#    the fallback extraction is defensive: an unparseable or comment-less result
+#    is treated exactly like a missing one.
+DOCS_HAS_GAPS=$(pipe_get_env "$DOCS_ENV" DOCS_HAS_GAPS); DOCS_HAS_GAPS=${DOCS_HAS_GAPS:-false}
+DOCS_CHANGED=$(pipe_get_env "$DOCS_ENV" DOCS_CHANGED);   DOCS_CHANGED=${DOCS_CHANGED:-false}
+DOCS_BODY=$(pipe_get_env "$DOCS_ENV" DOCS_COMMENT_PATH); DOCS_BODY=${DOCS_BODY:-$PIPE_CONTEXT_DIR/docs-sync-body.md}
+if [ ! -s "$DOCS_BODY" ] && [ -f "$PIPE_RESULT_DOCSSYNC" ]; then
+  RESULT_BODY="$PIPE_CONTEXT_DIR/docs-sync-result-body.md"
+  jq -re '.comment // empty' "$PIPE_RESULT_DOCSSYNC" > "$RESULT_BODY" 2>/dev/null || true
+  if [ -s "$RESULT_BODY" ]; then
+    DOCS_BODY="$RESULT_BODY"
+  fi
+fi
+
+DOCS_FAILED=false
+if [ -s "$DOCS_BODY" ]; then
+  {
+    printf '%s\n\n' "$DOCS_MARKER"
+    cat "$DOCS_BODY"
+  } > "$COMMENT_FILE"
+else
+  DOCS_FAILED=true
+  {
+    printf '%s\n\n⚠️ ' "$DOCS_MARKER"
+    pipe_failure_notice_files "documentation sync" \
+      "check by hand whether these changes need updates under $PIPE_DOCS_ROOTS" \
+      "$PIPE_AGENT_STDERR" "$PIPE_RESULT_DOCSSYNC"
+  } > "$COMMENT_FILE"
+fi
+
+# 9. Always post the verdict. Metrics reflect the runner's actual commit
+# decision, not the skill's informational DOCS_CHANGED marker.
+DOCS_COMMITTED=false
+emit_docs_metric() {
+  pipe_metric_event docs-sync docs_sync_gaps \
+    "$(jq -n --arg m "$DOCS_MODE" \
+        --argjson g "$([ "$DOCS_HAS_GAPS" = "true" ] && echo true || echo false)" \
+        --argjson c "$([ "$DOCS_COMMITTED" = "true" ] && echo true || echo false)" \
+        --argjson f "$([ "$DOCS_FAILED" = "true" ] && echo true || echo false)" \
+        '{mode: $m, has_gaps: $g, changed: $c, failed: $f}')"
+}
+
+platform_post_comment_file "$COMMENT_FILE"
+
+# 10. Commit and push what the agent applied. A failed agent applied nothing, so
+#     the notice posted above is the whole output and the exit is 0: an
+#     automation outage is not a documentation gap.
+if [ "$DOCS_FAILED" = "true" ]; then
+  emit_docs_metric
+  pipe_log "Agent did not complete, manual-review notice posted, nothing to commit"
+  exit 0
+fi
+if [ "$DOCS_MODE" != "apply" ]; then
+  emit_docs_metric
+  exit 0
+fi
+if [ "$DOCS_CHANGED" != "true" ]; then
+  pipe_log "Skill reported no documentation edits, checking the staged diff anyway"
+fi
+
+# Stage each root on its own: one missing root must not stop the others from
+# being staged, which a single `git add` of the whole set would do.
+for root in "${DOCS_ROOTS[@]}"; do
+  [ -e "$root" ] || continue
+  git add -- "$root" || true
+done
+if git diff --cached --quiet; then
+  emit_docs_metric
+  pipe_log "No documentation changes staged, nothing to commit"
+  exit 0
+fi
+
+git commit -m "$PIPE_COMMIT_DOCSSYNC"
+DOCS_COMMITTED=true
+emit_docs_metric
+
+# The agent may only touch the documentation roots, but an edit outside them
+# would leave the working tree dirty and abort the rebase below before it
+# starts, after which `git rebase --abort` fails too. Discard out-of-scope
+# edits so the tree is clean, enforcing the documented boundary.
+if ! git diff --quiet; then
+  pipe_log "Discarding out-of-scope working-tree changes left outside $PIPE_DOCS_ROOTS:"
+  git diff --name-only
+  git checkout -- .
+fi
+
+pipe_rebase_and_push
+pipe_log "Pushed the docs-sync commit, a new pipeline will run"