port: index DECISIONS.md -- it already answered last iteration's question

Last iteration I filed title and title_jp's disagreement with sylpheed-cli as
mechanism-unknown, to the Decoder as well as here. Both were already explained in
this file, under headings that name the two screens.

Checked rather than assumed. title: still ties on 0x8083, 0x80a0 and 0x8010, and
the export declares paint_order_ties unresolved; the old entry's 904 px in the
glow band matches my 790 px at the same place, same 4-6/255 magnitude. title_jp:
the 'only non-integer scale' claim finds 26 keyframes export-wide, but exactly
ONE element visible at rest -- ptlogo_eff2 at 125% -- which is the pose
verify-screen uses. It survives narrowly.

The failure is navigability: 6502 lines, 111 sections, no index, so 'has this
been decided?' had no cheap answer and re-deriving it looked like diligence.

index-decisions generates the contents; check-all runs --check. No line numbers
(the first version was a fixpoint that failed its own check, and appends would
invalidate them all), and checked, because a stale index answers 'already
decided?' with a confident no.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N7FiFFFwbvG2uxdcEh8HyF

tools/port/check-all

@@ -39,6 +39,9 @@ step format-validator must-pass "$BIN" check
 step modding-rules    must-pass tools/port/check-modding
 step capture-controls must-pass tools/port/check-capture-controls
 step menu-audio       must-pass env OUT="$OUT/audio" tools/port/verify-menu-audio
+# A stale index is worse than none: it answers "is this already decided?" with a
+# confident no. That is not hypothetical -- see the entry it was built after.
+step decisions-index  must-pass tools/port/index-decisions --check
 echo
 echo "reported, not asserted:"
 step oracle-captures  report-only env OUT="$OUT/oracle" tools/port/verify-capture

tools/port/index-decisions

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Regenerate the contents block at the top of `docs/port/DECISIONS.md`.
+#
+#   tools/port/index-decisions            # rewrite the index
+#   tools/port/index-decisions --check    # fail if it is out of date
+#
+# 🔴 WHY THIS EXISTS. The record reached 6 500 lines and 111 sections with no
+# index, and on 2026-08-30 I spent an iteration empirically re-deriving a result
+# it already contained -- under two headings that name the screens in question --
+# then reported the question as unexplained to the Decoder. An unnavigable record
+# is not a record that is hard to read; it is one that does not get read.
+#
+# ⚠️ `--check` exists because a stale index is worse than none: it would answer
+# "is this already decided?" with a confident no. `check-all` runs it.
+set -euo pipefail
+cd "${PROJECT_DIR:-/work}"
+DOC=docs/port/DECISIONS.md
+BEG='<!-- INDEX: generated by tools/port/index-decisions -- do not hand-edit -->'
+END='<!-- /INDEX -->'
+
+body=$(python3 - "$DOC" <<'PY'
+import re, sys
+lines = open(sys.argv[1]).read().split('\n')
+out = []
+for l in lines:
+    if l.startswith('## '):
+        title = l[3:].strip()
+        # A GitHub anchor: lowercased, punctuation dropped, spaces to hyphens.
+        anchor = re.sub(r'[^\w\s-]', '', title.lower()).strip().replace(' ', '-')
+        # NO LINE NUMBERS. They would make the index a fixpoint problem -- writing
+        # it shifts every line below it -- and, worse, every appended section
+        # would silently invalidate all of them. An anchor survives both.
+        out.append(f"* [{title}](#{anchor})")
+print('\n'.join(out))
+PY
+)
+new=$(printf '%s\n\n%d sections. Search this before re-deriving anything.\n\n%s\n\n%s\n' \
+  "$BEG" "$(grep -c '^## ' "$DOC")" "$body" "$END")
+
+cur=$(awk -v b="$BEG" -v e="$END" 'index($0,b){f=1} f{print} index($0,e){f=0}' "$DOC")
+
+if [ "${1:-}" = --check ]; then
+  if [ "$cur" = "$new" ]; then echo "  index-decisions            ok"; exit 0
+  else echo "  index-decisions            🔴 the index is out of date -- run tools/port/index-decisions"; exit 1; fi
+fi
+
+python3 - "$DOC" "$BEG" "$END" "$new" <<'PY'
+import sys
+doc, beg, end, new = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4]
+s = open(doc).read()
+if beg in s:
+    i, j = s.index(beg), s.index(end) + len(end)
+    s = s[:i] + new.rstrip('\n') + s[j:]
+else:
+    # First run: place it after the H1 and its opening paragraph.
+    k = s.index('\n## ')
+    s = s[:k] + '\n\n' + new.rstrip('\n') + s[k:]
+open(doc, 'w').write(s)
+print("index written")
+PY