@jenga-ai/agent 3.4.0 → 3.6.0

package/skills/j-gitignore/assets/jenga-paths.txt

@@ -0,0 +1,50 @@
+# skills/j-gitignore/assets/jenga-paths.txt
+#
+# The canonical catalog of Jenga-owned paths a consuming project may end up
+# with on disk. Consumed by audit-gitignore.sh, repair-gitignore.sh and
+# untrack-jenga-files.sh — all three read this one file, so the path surface
+# is defined in exactly one place.
+#
+# Format: <tier>TAB<path>TAB<description>
+# Blank lines and lines starting with '#' are ignored.
+#
+# Trailing '/' marks a directory entry and is preserved verbatim into
+# .gitignore (git treats 'foo/' as directory-only, which is what we want).
+#
+# ─── Tiers ───────────────────────────────────────────────────────────────────
+#
+#   scaffold  Entirely Jenga-owned. Regenerated wholesale by `npm postinstall`
+#             or `/distribute`, so nothing of yours is ever lost by ignoring
+#             them. Safe default.
+#
+#   hybrid    A Jenga-managed block inside a file that ALSO holds your own
+#             content. lib/generate-agent-context.js and
+#             lib/generate-copilot-instructions.js both replace only their
+#             managed block and preserve everything outside it. Ignoring these
+#             therefore also hides YOUR prose from the repo. Opt-in, never
+#             applied without the user saying so.
+#
+#   board     The project/ working tree (scrum board, todo.md, queue/,
+#             rapports/, logs/). Governed by jenga.config.json's
+#             `project_files_visibility`. Teams that share a board want this
+#             tracked; solo users usually do not. Opt-in.
+#
+#   optional  Defensive entries for paths no current Jenga version generates.
+#             Costs nothing to ignore, guards against a future or third-party
+#             agent surface appearing. Opt-in.
+#
+# ─────────────────────────────────────────────────────────────────────────────
+
+scaffold	.claude/	Claude Code skill/agent mirror — rewritten by every postinstall and /distribute run (scripts/postinstall.js targetRoots). Contains .jenga-postinstall-manifest.json.
+scaffold	.agents/	Copilot/Codex skill/agent mirror — the second of postinstall.js's two targetRoots. Contains .jenga-postinstall-manifest.json.
+scaffold	.jenga/	`jenga` CLI state directory. lib/commands/init.js already appends this entry itself; listed here so the audit reports it consistently.
+scaffold	.jenga-version	Installed-version stamp written at consumer root by scripts/postinstall.js.
+scaffold	jenga.config.json	Jenga project config (project_files_visibility, scaffold_visibility). SEE THE WARNING IN SKILL.md — ignoring this means a fresh clone loses your visibility settings.
+scaffold	.github/hooks/jenga.json	Copilot CLI hook wiring. "Entirely Jenga-owned output" per scripts/postinstall.js — no user content, unlike copilot-instructions.md.
+scaffold	J-CLAUDE.md	Collision-case copy written only when you already had your own CLAUDE.md. A J- file can only ever have been created by Jenga.
+scaffold	J-AGENTS.md	Collision-case copy written only when you already had your own AGENTS.md. Jenga-created by definition.
+hybrid	CLAUDE.md	Jenga writes a managed block here and preserves content outside it. May contain your own instructions.
+hybrid	AGENTS.md	Same managed-block treatment as CLAUDE.md, for Codex and generic AGENTS.md consumers.
+hybrid	.github/copilot-instructions.md	Managed-block bootstrap. postinstall.js explicitly notes this one is NOT entirely Jenga-owned.
+board	project/	The whole Jenga working tree. Mirrors what apply-project-visibility.sh's JENGA_WORKING_PATHS appends at init time.
+optional	.copilot/	Not generated by any current Jenga version (grepped across lib/, scripts/, skills/). Defensive only.

package/skills/j-gitignore/scripts/_catalog.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# -----------------------------------------------------------------------------
+# skills/j-gitignore/scripts/_catalog.sh
+#
+# Shared helpers for the j-gitignore scripts. Sourced, never run directly:
+#
+#   source "$(dirname "${BASH_SOURCE[0]}")/_catalog.sh"
+#
+# Provides:
+#   CATALOG_FILE            absolute path to assets/jenga-paths.txt
+#   MANAGED_BEGIN/_END      the managed-block markers
+#   load_catalog <tiers>    populates CATALOG_PATHS/_TIERS/_DESCS arrays
+#   validate_tiers <csv>    rejects an unknown tier name
+#   resolve_root <dir>      cd's to a project root, verifying it is a git repo
+#
+# The leading underscore marks this as internal to the skill — it is not an
+# entry point and takes no arguments of its own.
+# -----------------------------------------------------------------------------
+
+# Deliberately no `set -e` — callers handle their own errors, matching the
+# convention in skills/j-init/scripts/apply-scaffold-visibility.sh.
+set -uo pipefail
+
+_CATALOG_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CATALOG_FILE="${_CATALOG_LIB_DIR}/../assets/jenga-paths.txt"
+
+MANAGED_BEGIN="# >>> jenga:gitignore >>>"
+MANAGED_END="# <<< jenga:gitignore <<<"
+
+VALID_TIERS="scaffold hybrid board optional"
+
+# Populated by load_catalog.
+CATALOG_PATHS=()
+CATALOG_TIERS=()
+CATALOG_DESCS=()
+
+validate_tiers() {
+  local csv="$1" tier valid found
+  [ -n "$csv" ] || { echo "ERROR: --tiers was given an empty value." >&2; return 2; }
+  # Split on commas into an array FIRST, then restore IFS. Setting IFS=',' for
+  # the duration of both loops would stop the space-separated $VALID_TIERS from
+  # splitting, making every tier look invalid.
+  local -a requested=()
+  local old_ifs="$IFS"
+  IFS=','; read -r -a requested <<< "$csv"; IFS="$old_ifs"
+  for tier in "${requested[@]}"; do
+    found=0
+    for valid in $VALID_TIERS; do
+      [ "$tier" = "$valid" ] && found=1 && break
+    done
+    if [ "$found" -eq 0 ]; then
+      echo "ERROR: Unknown tier '${tier}'. Valid tiers: ${VALID_TIERS// /, }" >&2
+      return 2
+    fi
+  done
+  return 0
+}
+
+# load_catalog <comma-separated-tiers>
+# Reads CATALOG_FILE, keeping only rows whose tier is in the requested set.
+load_catalog() {
+  local want="$1"
+  CATALOG_PATHS=(); CATALOG_TIERS=(); CATALOG_DESCS=()
+
+  if [ ! -f "$CATALOG_FILE" ]; then
+    echo "ERROR: Path catalog not found: $CATALOG_FILE" >&2
+    return 1
+  fi
+
+  local tier path desc
+  while IFS=$'\t' read -r tier path desc || [ -n "${tier:-}" ]; do
+    [ -z "${tier// /}" ] && continue
+    case "$tier" in \#*) continue ;; esac
+    [ -n "${path:-}" ] || continue
+    case ",${want}," in
+      *",${tier},"*)
+        CATALOG_PATHS+=("$path")
+        CATALOG_TIERS+=("$tier")
+        CATALOG_DESCS+=("${desc:-}")
+        ;;
+    esac
+  done < "$CATALOG_FILE"
+
+  if [ "${#CATALOG_PATHS[@]}" -eq 0 ]; then
+    echo "ERROR: No catalog entries matched tiers '${want}'." >&2
+    return 1
+  fi
+  return 0
+}
+
+# resolve_root <dir> — cd into it and confirm it is the root of a git work tree.
+resolve_root() {
+  local root="$1"
+  if [ ! -d "$root" ]; then
+    echo "ERROR: Project root does not exist: $root" >&2
+    return 1
+  fi
+  cd "$root" || { echo "ERROR: Cannot enter project root: $root" >&2; return 1; }
+  if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    echo "ERROR: Not a git repository: $root" >&2
+    echo "       This skill repairs a project's tracked/ignored state, so it needs git." >&2
+    return 1
+  fi
+  return 0
+}

package/skills/j-gitignore/scripts/audit-gitignore.sh

@@ -0,0 +1,194 @@
+#!/usr/bin/env bash
+# -----------------------------------------------------------------------------
+# skills/j-gitignore/scripts/audit-gitignore.sh
+#
+# Read-only. Reports the Jenga-related git state of an already-scaffolded
+# project. Changes nothing — this is the "check" half of the skill, safe to run
+# anywhere, any number of times.
+#
+# Reports three independent things per catalog path:
+#
+#   entry     Is the exact entry literally present in .gitignore?
+#   ignored   Does git actually ignore the path (`git check-ignore`)? This can
+#             be true via a broader rule even when `entry` is no — and is
+#             ALWAYS reported as "no" for a tracked path, because .gitignore
+#             has no effect on a file git already tracks. That divergence is
+#             the single most common cause of "I ignored it and it still keeps
+#             getting committed".
+#   tracked   Does git currently track anything under the path?
+#
+# Plus the stray-heredoc-terminator check: a bare `EOF` line left behind by the
+# botched `cat > .gitignore <<EOF` in pre-fix /init scaffolds (fixed for NEW
+# projects by E31_S07_T02/T03 and E42_S06_T01, which replaced the heredoc with
+# a `cp` from assets/.gitignore_template — forward-only, so already-scaffolded
+# projects still carry the damage).
+#
+# Invoked via `bash`, not executed directly — ships without the executable bit,
+# same convention as skills/j-cloud-connect/scripts/install-rclone.sh.
+#
+# Usage:
+#   audit-gitignore.sh [project_root] [--tiers scaffold,hybrid,board,optional]
+#
+# Exit codes:
+#   0   Audit ran; nothing to fix
+#   1   Bad usage or missing prerequisite (not a git repo, catalog missing)
+#   2   Invalid tier name
+#   10  Audit ran; findings exist (stray terminators, missing entries, or
+#       tracked paths). Not an error — this is the signal to run the repair.
+# -----------------------------------------------------------------------------
+
+set -uo pipefail
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/_catalog.sh"
+
+PROJECT_ROOT=""
+TIERS="scaffold"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --tiers)   TIERS="${2:-}"; shift 2 ;;
+    --tiers=*) TIERS="${1#*=}"; shift ;;
+    -h|--help)
+      echo "Usage: $(basename "$0") [project_root] [--tiers scaffold,hybrid,board,optional]"
+      exit 0 ;;
+    -*)
+      echo "ERROR: Unknown option: $1" >&2
+      echo "Usage: $(basename "$0") [project_root] [--tiers <csv>]" >&2
+      exit 1 ;;
+    *)
+      if [ -n "$PROJECT_ROOT" ]; then
+        echo "ERROR: More than one project root given: '$PROJECT_ROOT' and '$1'" >&2
+        exit 1
+      fi
+      PROJECT_ROOT="$1"; shift ;;
+  esac
+done
+
+PROJECT_ROOT="${PROJECT_ROOT:-$PWD}"
+validate_tiers "$TIERS" || exit 2
+resolve_root "$PROJECT_ROOT" || exit 1
+load_catalog "$TIERS" || exit 1
+
+GITIGNORE=".gitignore"
+FINDINGS=0
+
+echo "═══════════════════════════════════════════════════════════════════════"
+echo " Jenga gitignore audit — $(pwd)"
+echo " Tiers: ${TIERS}"
+echo "═══════════════════════════════════════════════════════════════════════"
+echo
+
+# ─── 1. Stray heredoc terminators ───────────────────────────────────────────
+echo "── 1. Stray heredoc terminators ───────────────────────────────────────"
+STRAY_COUNT=0
+if [ ! -f "$GITIGNORE" ]; then
+  echo "  No .gitignore at this root — nothing to check."
+else
+  # A line that is exactly EOF (tolerating trailing whitespace). Reported with
+  # line numbers so a human can eyeball it before anything is removed.
+  while IFS= read -r hit; do
+    [ -z "$hit" ] && continue
+    echo "  ✗ line ${hit%%:*}: stray '${hit#*:}' terminator"
+    STRAY_COUNT=$((STRAY_COUNT + 1))
+  done < <(grep -nE '^[[:space:]]*EOF[[:space:]]*$' "$GITIGNORE" 2>/dev/null)
+
+  if [ "$STRAY_COUNT" -eq 0 ]; then
+    echo "  ✓ Clean — no stray terminator lines."
+  else
+    echo
+    echo "  → ${STRAY_COUNT} stray line(s). repair-gitignore.sh removes these."
+    FINDINGS=$((FINDINGS + STRAY_COUNT))
+  fi
+fi
+echo
+
+# ─── 2. Managed block ────────────────────────────────────────────────────────
+echo "── 2. Managed block ───────────────────────────────────────────────────"
+if [ -f "$GITIGNORE" ] && grep -qxF -- "$MANAGED_BEGIN" "$GITIGNORE"; then
+  echo "  ✓ Present — this project has been through repair-gitignore.sh before."
+else
+  echo "  · Absent — entries (if any) are loose, e.g. appended by /init's"
+  echo "    apply-project-visibility.sh / apply-scaffold-visibility.sh."
+fi
+echo
+
+# ─── 3. Per-path state ───────────────────────────────────────────────────────
+echo "── 3. Per-path state ──────────────────────────────────────────────────"
+printf "  %-34s %-7s %-8s %-8s %s\n" "PATH" "ENTRY" "IGNORED" "TRACKED" "TIER"
+printf "  %-34s %-7s %-8s %-8s %s\n" "----" "-----" "-------" "-------" "----"
+
+MISSING_ENTRIES=0
+TRACKED_PATHS=()
+
+for i in "${!CATALOG_PATHS[@]}"; do
+  path="${CATALOG_PATHS[$i]}"
+  tier="${CATALOG_TIERS[$i]}"
+
+  entry="no"
+  if [ -f "$GITIGNORE" ] && grep -qxF -- "$path" "$GITIGNORE"; then
+    entry="yes"
+  fi
+
+  # check-ignore works on paths that do not exist on disk, so a not-yet-created
+  # scaffold dir is still evaluated against the rules.
+  ignored="no"
+  if git check-ignore -q -- "$path" 2>/dev/null; then
+    ignored="yes"
+  fi
+
+  tracked="no"
+  if [ -n "$(git ls-files -- "$path" 2>/dev/null | head -n 1)" ]; then
+    tracked="yes"
+    TRACKED_PATHS+=("$path")
+  fi
+
+  flag=""
+  if [ "$entry" = "no" ];   then flag="  ← no entry"; MISSING_ENTRIES=$((MISSING_ENTRIES + 1)); fi
+  if [ "$tracked" = "yes" ]; then flag="${flag}  ← TRACKED"; fi
+
+  printf "  %-34s %-7s %-8s %-8s %s%s\n" "$path" "$entry" "$ignored" "$tracked" "$tier" "$flag"
+done
+echo
+
+# ─── 4. Origin state ─────────────────────────────────────────────────────────
+echo "── 4. Origin ──────────────────────────────────────────────────────────"
+BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null)"
+UPSTREAM="$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null)"
+
+if [ -z "$UPSTREAM" ]; then
+  echo "  · Branch '${BRANCH}' has no upstream — nothing has been pushed from it."
+  echo "    Untracking here only ever affects local history."
+else
+  echo "  Upstream: ${UPSTREAM}"
+  ON_ORIGIN=0
+  for path in "${TRACKED_PATHS[@]:-}"; do
+    [ -z "$path" ] && continue
+    if [ -n "$(git ls-tree -r --name-only "$UPSTREAM" -- "$path" 2>/dev/null | head -n 1)" ]; then
+      echo "  ✗ ${path} — present on ${UPSTREAM}"
+      ON_ORIGIN=$((ON_ORIGIN + 1))
+    fi
+  done
+  if [ "$ON_ORIGIN" -eq 0 ]; then
+    echo "  ✓ No catalog path is present on ${UPSTREAM}."
+  else
+    echo
+    echo "  → ${ON_ORIGIN} path(s) live on the remote. untrack-jenga-files.sh"
+    echo "    --commit --push removes them from the branch TIP. It does NOT"
+    echo "    rewrite history — earlier commits still contain them."
+  fi
+fi
+echo
+
+# ─── Summary ─────────────────────────────────────────────────────────────────
+FINDINGS=$((FINDINGS + MISSING_ENTRIES + ${#TRACKED_PATHS[@]}))
+echo "═══════════════════════════════════════════════════════════════════════"
+echo " Stray terminators : ${STRAY_COUNT}"
+echo " Missing entries   : ${MISSING_ENTRIES}"
+echo " Tracked paths     : ${#TRACKED_PATHS[@]}"
+echo "═══════════════════════════════════════════════════════════════════════"
+
+if [ "$FINDINGS" -gt 0 ]; then
+  echo "AUDIT_RESULT=findings"
+  exit 10
+fi
+echo "AUDIT_RESULT=clean"
+exit 0

package/skills/j-gitignore/scripts/repair-gitignore.sh

@@ -0,0 +1,226 @@
+#!/usr/bin/env bash
+# -----------------------------------------------------------------------------
+# skills/j-gitignore/scripts/repair-gitignore.sh
+#
+# Repairs an already-scaffolded project's .gitignore. Two jobs, in order:
+#
+#   1. Strips stray heredoc terminator lines (a bare `EOF`) left behind by the
+#      botched `cat > .gitignore <<EOF` in pre-fix /init scaffolds. The upstream
+#      fix (E31_S07_T02/T03, E42_S06_T01) repaired the TEMPLATE, which only helps
+#      projects scaffolded afterwards; this repairs one already on disk.
+#
+#   2. Adds (mode `ignored`) or removes (mode `visible`) the Jenga path entries,
+#      inside a managed block so the operation is exactly reversible.
+#
+# The managed block also ABSORBS loose duplicates: /init's
+# apply-project-visibility.sh and apply-scaffold-visibility.sh append bare lines
+# with no markers, so a previously-initialised project has loose `project/`,
+# `.claude/` and `.agents/` entries. Any loose line exactly matching a selected
+# catalog path is pulled out of the file and re-emitted inside the block, rather
+# than left to sit alongside it as a duplicate.
+#
+# Everything outside the managed block is preserved byte for byte. The file is
+# written atomically (temp + mv), so an interrupted run cannot truncate it.
+#
+# This does NOT untrack anything. .gitignore has no effect on a file git already
+# tracks — that is untrack-jenga-files.sh's job, and it must run after this.
+#
+# Invoked via `bash`, not executed directly.
+#
+# Usage:
+#   repair-gitignore.sh <ignored|visible> [project_root]
+#                       [--tiers scaffold,hybrid,board,optional]
+#                       [--dry-run] [--keep-eof]
+#
+# Options:
+#   --tiers <csv>  Which catalog tiers to act on. Default: scaffold
+#   --dry-run      Print a unified diff of the intended change; write nothing.
+#   --keep-eof     Leave stray `EOF` lines alone. Use only if this project
+#                  genuinely means to ignore a file literally named EOF.
+#
+# Exit codes:
+#   0  Success (including "already correct — nothing to do")
+#   1  Bad usage or missing prerequisite
+#   2  Invalid mode or tier
+#   3  Filesystem write failure
+# -----------------------------------------------------------------------------
+
+set -uo pipefail
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/_catalog.sh"
+
+info() { echo "[gitignore-repair] $*"; }
+err()  { echo "[gitignore-repair] ERROR: $*" >&2; }
+
+MODE=""
+PROJECT_ROOT=""
+TIERS="scaffold"
+DRY_RUN=0
+KEEP_EOF=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --tiers)   TIERS="${2:-}"; shift 2 ;;
+    --tiers=*) TIERS="${1#*=}"; shift ;;
+    --dry-run) DRY_RUN=1; shift ;;
+    --keep-eof) KEEP_EOF=1; shift ;;
+    -h|--help)
+      echo "Usage: $(basename "$0") <ignored|visible> [project_root] [--tiers <csv>] [--dry-run] [--keep-eof]"
+      exit 0 ;;
+    -*) err "Unknown option: $1"; exit 1 ;;
+    *)
+      if [ -z "$MODE" ]; then MODE="$1"
+      elif [ -z "$PROJECT_ROOT" ]; then PROJECT_ROOT="$1"
+      else err "Unexpected argument: $1"; exit 1
+      fi
+      shift ;;
+  esac
+done
+
+case "$MODE" in
+  ignored|visible) ;;
+  "") err "Missing mode. Usage: $(basename "$0") <ignored|visible> [project_root]"; exit 1 ;;
+  *)  err "Invalid mode '${MODE}'. Allowed: ignored, visible"; exit 2 ;;
+esac
+
+PROJECT_ROOT="${PROJECT_ROOT:-$PWD}"
+validate_tiers "$TIERS" || exit 2
+resolve_root "$PROJECT_ROOT" || exit 1
+load_catalog "$TIERS" || exit 1
+
+GITIGNORE=".gitignore"
+TMP="${GITIGNORE}.jenga-repair.$$"
+cleanup() { rm -f "$TMP"; }
+trap cleanup EXIT
+
+# Fast membership test for "is this line one of our selected catalog paths".
+is_catalog_path() {
+  local line="$1" p
+  for p in "${CATALOG_PATHS[@]}"; do
+    [ "$line" = "$p" ] && return 0
+  done
+  return 1
+}
+
+# ─── Read the existing file ─────────────────────────────────────────────────
+ORIGINAL=()
+if [ -f "$GITIGNORE" ]; then
+  while IFS= read -r line || [ -n "$line" ]; do
+    ORIGINAL+=("$line")
+  done < "$GITIGNORE"
+elif [ "$MODE" = "visible" ]; then
+  info "No .gitignore at this root and mode is 'visible' — nothing to do."
+  exit 0
+else
+  info "No .gitignore at this root — creating one."
+fi
+
+# ─── Filter: drop stray terminators, the old managed block, loose dupes ─────
+FILTERED=()
+in_block=0
+removed_eof=0
+removed_loose=0
+had_block=0
+
+for line in "${ORIGINAL[@]+"${ORIGINAL[@]}"}"; do
+  if [ "$in_block" -eq 1 ]; then
+    [ "$line" = "$MANAGED_END" ] && in_block=0
+    continue
+  fi
+  if [ "$line" = "$MANAGED_BEGIN" ]; then
+    in_block=1; had_block=1; continue
+  fi
+  if [ "$KEEP_EOF" -eq 0 ] && [[ "$line" =~ ^[[:space:]]*EOF[[:space:]]*$ ]]; then
+    removed_eof=$((removed_eof + 1)); continue
+  fi
+  if is_catalog_path "$line"; then
+    removed_loose=$((removed_loose + 1)); continue
+  fi
+  FILTERED+=("$line")
+done
+
+if [ "$in_block" -eq 1 ]; then
+  err "Unterminated managed block — found '${MANAGED_BEGIN}' with no matching end marker."
+  err "Refusing to write. Fix ${GITIGNORE} by hand, then re-run."
+  exit 3
+fi
+
+# Trim trailing blank lines so repeated runs cannot accumulate whitespace.
+# Indexed from the end by arithmetic, NOT via ${arr[-1]}: macOS still ships
+# bash 3.2, which has no negative array subscripts — there the subscript
+# silently evaluates empty, the loop condition stays true, and nothing is ever
+# unset, so the script spins forever.
+_last=$(( ${#FILTERED[@]} - 1 ))
+while [ "$_last" -ge 0 ] && [ -z "${FILTERED[$_last]// /}" ]; do
+  unset "FILTERED[$_last]"
+  _last=$(( _last - 1 ))
+done
+
+# ─── Build the new file ─────────────────────────────────────────────────────
+: > "$TMP" || { err "Cannot write temp file: $TMP"; exit 3; }
+
+for line in "${FILTERED[@]+"${FILTERED[@]}"}"; do
+  printf '%s\n' "$line" >> "$TMP" || { err "Write failed: $TMP"; exit 3; }
+done
+
+if [ "$MODE" = "ignored" ]; then
+  [ "${#FILTERED[@]}" -gt 0 ] && printf '\n' >> "$TMP"
+  {
+    printf '%s\n' "$MANAGED_BEGIN"
+    printf '%s\n' "# Managed by j.gitignore — regenerate with:"
+    printf '%s\n' "#   bash <skill>/scripts/repair-gitignore.sh ignored . --tiers ${TIERS}"
+    printf '%s\n' "# Remove with the same script in 'visible' mode. Edits inside this block"
+    printf '%s\n' "# are overwritten; put your own patterns outside it."
+    for i in "${!CATALOG_PATHS[@]}"; do
+      printf '%s\n' "${CATALOG_PATHS[$i]}"
+    done
+    printf '%s\n' "$MANAGED_END"
+  } >> "$TMP" || { err "Write failed: $TMP"; exit 3; }
+fi
+
+# ─── Report / apply ─────────────────────────────────────────────────────────
+if [ -f "$GITIGNORE" ] && cmp -s "$GITIGNORE" "$TMP"; then
+  info "Already correct — ${GITIGNORE} needs no change."
+  exit 0
+fi
+
+echo
+echo "── Proposed change to ${GITIGNORE} ────────────────────────────────────"
+if [ -f "$GITIGNORE" ]; then
+  diff -u "$GITIGNORE" "$TMP" | sed 's/^/  /' || true
+else
+  sed 's/^/  + /' "$TMP"
+fi
+echo
+
+info "Stray 'EOF' terminators removed : ${removed_eof}"
+info "Loose duplicate entries folded in: ${removed_loose}"
+info "Pre-existing managed block       : $([ "$had_block" -eq 1 ] && echo replaced || echo none)"
+info "Mode                             : ${MODE} (tiers: ${TIERS})"
+
+if [ "$DRY_RUN" -eq 1 ]; then
+  info "--dry-run — nothing written."
+  exit 0
+fi
+
+if ! mv "$TMP" "$GITIGNORE"; then
+  err "Failed to move ${TMP} into place."
+  exit 3
+fi
+trap - EXIT
+
+# Never report success without re-verifying the result on disk.
+if [ "$MODE" = "ignored" ]; then
+  for p in "${CATALOG_PATHS[@]}"; do
+    if ! grep -qxF -- "$p" "$GITIGNORE"; then
+      err "Post-write verification failed: '${p}' is not in ${GITIGNORE}."
+      exit 3
+    fi
+  done
+fi
+if [ "$KEEP_EOF" -eq 0 ] && grep -qE '^[[:space:]]*EOF[[:space:]]*$' "$GITIGNORE"; then
+  err "Post-write verification failed: a stray EOF line survived."
+  exit 3
+fi
+
+info "Wrote ${GITIGNORE} (verified)."
+exit 0