Add graduation detection, scoped staging, and reorder-commits script

Author: j0ntz

.cursor/rules/typescript-standards.mdc

@@ -130,6 +130,29 @@ Exception: Empty handlers are acceptable ONLY when the rejection is an expected
 Exception: Auto-load effects where infinite retry on persistent failure is undesirable — keep `== null` there and allow retry only via explicit user action.
 </standard>
 
+<standard id="file-structure">Component files (`.tsx`) and utility files (`.ts`) follow a consistent section ordering.
+
+**File-level ordering:**
+1. Imports
+2. Types / Interfaces — exported types first, then internal `Props`
+3. Constants
+4. Main component (`export const Scene: React.FC<Props>`)
+5. Sub-components (internal, non-exported)
+6. Styles (`getStyles` / `cacheStyles`)
+7. Helpers / utility functions — pure functions at the very end of the file
+
+**Component body ordering:**
+1. Props destructuring
+2. Theme / styles (`useTheme`, `getStyles`)
+3. State (`useState`)
+4. Refs (`useRef`)
+5. Selectors (`useSelector`, `useWatch`)
+6. Derived values / `useMemo`
+7. Handlers (`useHandler`)
+8. Effects (`useEffect`, `useBackEvent`)
+9. Return JSX
+</standard>
+
 </standards>
 
 <lint-fix-patterns description="Common ESLint fix recipes for this project's config. Apply directly — do not search node_modules for types. The `rule` attribute maps to ESLint rule IDs for automatic matching by `lint-warnings.sh`.">

.cursor/skills/im/SKILL.md

@@ -63,26 +63,26 @@ If the task spans multiple repos, note the additional repos but implement in the
 This script:
 
 1. Runs `eslint --fix`
-2. Shows any remaining lint findings grouped by rule
-3. Outputs matching fix patterns from `~/.cursor/rules/typescript-standards.mdc`
-4. Flags unmatched rules that need new patterns added
+2. Detects files that will be "graduated" from the warning suppression list on commit, promoting their suppressed-rule warnings to errors in the output
+3. Shows any remaining findings grouped by rule (with graduation promotions already applied)
+4. Outputs matching fix patterns from `~/.cursor/rules/typescript-standards.mdc`
+5. Flags unmatched rules that need new patterns added
 
 If the script auto-fixes files or remaining findings exist:
 
-1. Apply fixes for the remaining findings using the matched patterns in the output
-2. For **unmatched rules**: After fixing, add a new `<pattern id="..." rule="...">` to `typescript-standards.mdc` so future occurrences have guidance
-3. Commit the pre-existing lint changes separately:
+1. Fix all reported **errors** first — these include graduation-promoted warnings that will block `lint-commit.sh` after the file is removed from the suppression list
+2. Fix remaining **warnings** using the matched patterns in the output
+3. For **unmatched rules**: After fixing, add a new `<pattern id="..." rule="...">` to `typescript-standards.mdc` so future occurrences have guidance
+4. Commit the pre-existing lint changes separately:
    ```bash
    ~/.cursor/skills/lint-commit.sh -m "Fix lint warnings in <ComponentName>" <file1> <file2> ...
    ```
 
 **Architectural vs mechanical fixes**: If a pattern notes "architectural change" (e.g., `styled()` refactoring), flag to user rather than fixing inline — these changes have broader impact and may warrant separate discussion.
 
-`lint-commit.sh` treats passed file arguments as the primary commit scope, auto-includes generated companion files like `src/locales/strings`, `eslint.config.mjs`, and snapshots, and reports any additional non-generated files it stages.
+`lint-commit.sh` treats passed file arguments as the primary commit scope and only stages those files plus generated companion files (`src/locales/strings`, `eslint.config.mjs`, snapshots). It does not stage unrelated dirty files in the working tree.
 
 This ensures the subsequent feature commit introduces zero pre-existing lint findings. This is the initial pass — if you discover additional files to modify during Step 3, the same check applies (see Step 3).
-
-**Warning graduation (edge-react-gui)**: `edge-react-gui` has a suppression list in `eslint.config.mjs` that turns `explicit-function-return-type`, `strict-boolean-expressions`, `use-unknown-in-catch-callback-variable`, and `ban-ts-comment` to warning severity for ~300+ files. When `lint-commit.sh` commits a file, `update-eslint-warnings.ts` removes it from this list — "graduating" the file to full error enforcement. If a graduated file has pre-existing violations on lines you touched, `lint-commit.sh` Step 2b will block the commit. Running `lint-warnings.sh` here in Step 2 catches and fixes these issues before graduation occurs.
 </step>
 
 <step id="3" name="Implementation">
@@ -138,9 +138,13 @@ Other repos only have `## Unreleased` — no staging distinction.
 1. **Check for an open PR**: Run `gh pr view --json url,reviews 2>/dev/null` to determine if a PR exists and whether it has human review comments.
 2. **If a PR exists with human review comments**, skip cleanup — rewriting history would lose review context. Note the pending cleanup in the retrospective.
 3. **Otherwise (no PR, or PR with no human reviews)**, always perform ALL applicable cleanup automatically:
-   - **Fixup commits exist**: Autosquash with `GIT_SEQUENCE_EDITOR=true git rebase -i --autosquash <base-branch>`. Do this immediately — never leave fixup commits unsquashed.
-   - **Structural issues** (add-then-remove cycles, misplaced changes, commits that should be squashed, CHANGELOG in intermediate commits): Use scripted `GIT_SEQUENCE_EDITOR` to drop, reorder, or squash commits, resolving conflicts as needed. Verify the final tree matches the pre-restructure state with `git diff`.
-   - **Git lock conflicts**: VSCode's built-in git integration may race with rebase operations, creating `.git/index.lock` files. Always run `rm -f .git/index.lock` before any `git rebase` command to prevent stalls. If a rebase step fails with "index.lock: File exists", remove the lock and `git rebase --continue`.
+   - **Fixup commits exist**: Autosquash with `rm -f .git/index.lock && GIT_SEQUENCE_EDITOR=true git rebase -i --autosquash <base-branch>`. Do this immediately — never leave fixup commits unsquashed.
+   - **Reorder commits**: Use the companion script to reorder commits to the desired order. Hashes are oldest-to-newest:
+     ```bash
+     ~/.cursor/skills/im/scripts/reorder-commits.sh <base-branch> <hash1> <hash2> ...
+     ```
+     The script handles index lock cleanup, awk-based reordering, and verifies the tree is unchanged afterward.
+   - **Structural issues** (add-then-remove cycles, misplaced changes, commits that should be squashed, CHANGELOG in intermediate commits): Use `reorder-commits.sh` for reordering. For squash/drop operations, use `rm -f .git/index.lock && GIT_SEQUENCE_EDITOR="..." git rebase -i <base-branch>` with an awk or sed script. Verify the final tree matches the pre-restructure state with `git diff`.
      </step>
 
 <step id="5" name="Verification">

.cursor/skills/im/scripts/lint-warnings.sh

@@ -1,16 +1,19 @@
 #!/usr/bin/env bash
 # lint-warnings.sh
 # Run eslint --fix on files and match any remaining findings to documented fix
-# patterns.
+# patterns. Detects files that will be "graduated" from the ESLint warning
+# suppression list when committed, promoting their suppressed-rule warnings to
+# errors so they can be fixed before commit.
 #
 # Usage:
 #   lint-warnings.sh <file1> [file2] ...
 #
 # Output:
 #   1. Summary of auto-fixes applied (if any)
-#   2. Summary of remaining findings per rule/severity
-#   3. Matched patterns from typescript-standards.mdc (full XML blocks)
-#   4. Unmatched rules (need new patterns added)
+#   2. Graduation warnings (files that will be promoted to error severity)
+#   3. Summary of remaining findings per rule/severity
+#   4. Matched patterns from typescript-standards.mdc (full XML blocks)
+#   5. Unmatched rules (need new patterns added)
 #
 # Exit codes:
 #   0 - No remaining lint findings after auto-fix
@@ -92,23 +95,59 @@ if (!Array.isArray(results)) {
   process.exit(2);
 }
 
+// --- Graduation detection ---
+// Parse eslint.config.mjs to find files in the warning-suppression list.
+// These files currently have certain rules at "warn" severity, but committing
+// them removes them from the list (via update-eslint-warnings), promoting
+// those rules to "error". We detect this ahead of time so the agent can fix
+// them in a lint-fix commit before the feature commit.
+const GRADUATED_RULES = new Set([
+  "@typescript-eslint/ban-ts-comment",
+  "@typescript-eslint/explicit-function-return-type",
+  "@typescript-eslint/strict-boolean-expressions",
+  "@typescript-eslint/use-unknown-in-catch-callback-variable"
+]);
+
+const suppressedFiles = new Set();
+try {
+  const configPath = path.join(process.cwd(), "eslint.config.mjs");
+  const configContent = fs.readFileSync(configPath, "utf8");
+  // Extract file paths from the suppression block (single-quoted strings)
+  for (const m of configContent.matchAll(/^\s+\x27([^\x27]+)\x27,?\s*$/gm)) {
+    suppressedFiles.add(m[1]);
+  }
+} catch (error) {
+  // No eslint.config.mjs or parse failure — skip graduation detection
+}
+
 const findingsBySeverity = new Map([
   [2, new Map()],
   [1, new Map()]
 ]);
 let totalErrors = 0;
 let totalWarnings = 0;
+let graduatedCount = 0;
 let autoFixedFiles = 0;
 
 for (const file of results) {
   if (file != null && typeof file.output === "string") autoFixedFiles += 1;
 
   const rel = path.relative(process.cwd(), file.filePath);
+  const willGraduate = suppressedFiles.has(rel);
+
   for (const message of file.messages) {
     if (message.severity !== 1 && message.severity !== 2) continue;
 
-    const findingsForSeverity = findingsBySeverity.get(message.severity);
     const rule = message.ruleId || "unknown";
+
+    // Promote suppressed-rule warnings to errors for files that will graduate
+    let effectiveSeverity = message.severity;
+    if (willGraduate && message.severity === 1 && GRADUATED_RULES.has(rule)) {
+      effectiveSeverity = 2;
+      graduatedCount += 1;
+    }
+
+    const findingsForSeverity = findingsBySeverity.get(effectiveSeverity);
     if (!findingsForSeverity.has(rule)) {
       findingsForSeverity.set(rule, []);
     }
@@ -118,8 +157,8 @@ for (const file of results) {
       message: message.message
     });
 
-    if (message.severity === 2) totalErrors += 1;
-    if (message.severity === 1) totalWarnings += 1;
+    if (effectiveSeverity === 2) totalErrors += 1;
+    else totalWarnings += 1;
   }
 }
 
@@ -133,6 +172,10 @@ if (autoFixedFiles > 0) {
   console.log(`>> Auto-fixed ${autoFixedFiles} file(s)`);
 }
 
+if (graduatedCount > 0) {
+  console.log(`>> ${graduatedCount} warning(s) promoted to errors (graduation: file will be removed from suppression list on commit)`);
+}
+
 if (totalErrors === 0 && totalWarnings === 0) {
   console.log(">> No remaining lint findings");
   process.exit(0);

.cursor/skills/im/scripts/reorder-commits.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# reorder-commits.sh
+# Reorder commits on a branch to a specified order using non-interactive rebase.
+#
+# Usage:
+#   reorder-commits.sh <base-branch> <hash1> <hash2> ...
+#
+# Arguments:
+#   base-branch  The branch/ref to rebase onto (e.g., origin/develop)
+#   hash1..N     Commit hashes in desired order (oldest to newest)
+#
+# The script verifies all hashes exist in base..HEAD, writes an awk-based
+# GIT_SEQUENCE_EDITOR to reorder the pick lines, and runs git rebase -i.
+# It verifies the tree is unchanged after rebase.
+#
+# Exit codes:
+#   0 - Reorder successful
+#   1 - Reorder failed (conflict, missing commits, tree mismatch)
+set -euo pipefail
+
+if [[ $# -lt 3 ]]; then
+  echo "Usage: reorder-commits.sh <base-branch> <hash1> <hash2> ..." >&2
+  exit 1
+fi
+
+BASE="$1"
+shift
+DESIRED_ORDER=("$@")
+
+# Remove stale index locks
+rm -f .git/index.lock
+
+# Get short hashes for matching rebase todo lines
+BRANCH_COMMITS=$(git log --reverse --format='%h' "$BASE..HEAD")
+BRANCH_COUNT=$(echo "$BRANCH_COMMITS" | wc -l | tr -d ' ')
+DESIRED_COUNT=${#DESIRED_ORDER[@]}
+
+if [[ "$BRANCH_COUNT" -ne "$DESIRED_COUNT" ]]; then
+  echo "Error: Branch has $BRANCH_COUNT commits but $DESIRED_COUNT hashes were provided" >&2
+  echo "Branch commits: $BRANCH_COMMITS" >&2
+  exit 1
+fi
+
+# Resolve desired hashes to short hashes and verify they're on the branch
+DESIRED_SHORT=()
+for hash in "${DESIRED_ORDER[@]}"; do
+  short=$(git rev-parse --short "$hash" 2>/dev/null) || {
+    echo "Error: Cannot resolve hash '$hash'" >&2
+    exit 1
+  }
+  if ! echo "$BRANCH_COMMITS" | grep -q "^${short}$"; then
+    echo "Error: Commit $short is not in $BASE..HEAD" >&2
+    exit 1
+  fi
+  DESIRED_SHORT+=("$short")
+done
+
+# Capture pre-rebase tree for verification
+PRE_TREE=$(git rev-parse HEAD^{tree})
+
+# Build awk script that reorders pick lines to match desired order
+# The awk program collects all pick lines, then outputs them in the order
+# specified by the DESIRED env var (space-separated short hashes)
+EDITOR_SCRIPT=$(mktemp)
+trap 'rm -f "$EDITOR_SCRIPT"' EXIT
+
+cat > "$EDITOR_SCRIPT" << 'AWKSCRIPT'
+#!/usr/bin/env bash
+exec awk -v desired="$DESIRED" '
+BEGIN {
+  n = split(desired, order, " ")
+}
+/^pick / {
+  hash = $2
+  lines[hash] = $0
+  next
+}
+/^$/ || /^#/ { next }
+END {
+  for (i = 1; i <= n; i++) {
+    for (h in lines) {
+      if (index(h, order[i]) == 1 || index(order[i], h) == 1) {
+        print lines[h]
+        break
+      }
+    }
+  }
+}
+' "$1" > "$1.tmp" && mv "$1.tmp" "$1"
+AWKSCRIPT
+chmod +x "$EDITOR_SCRIPT"
+
+export DESIRED="${DESIRED_SHORT[*]}"
+if GIT_SEQUENCE_EDITOR="$EDITOR_SCRIPT" git rebase -i "$BASE" 2>/dev/null; then
+  POST_TREE=$(git rev-parse HEAD^{tree})
+  if [[ "$PRE_TREE" == "$POST_TREE" ]]; then
+    echo ">> Commits reordered successfully"
+    git log --oneline "$BASE..HEAD"
+  else
+    echo "Error: Tree changed after reorder (pre: $PRE_TREE, post: $POST_TREE)" >&2
+    echo "This indicates content was lost or modified during rebase." >&2
+    exit 1
+  fi
+else
+  git rebase --abort 2>/dev/null || true
+  echo "Error: Rebase failed (likely conflict). Aborted." >&2
+  exit 1
+fi

.cursor/skills/lint-commit.sh

@@ -182,9 +182,25 @@ if node -e "process.exit(require('./package.json').scripts?.localize ? 0 : 1)" 2
   yarn localize
 fi
 
-# Step 4: Stage everything and report effective commit scope
-echo ">> git add -A && git commit"
-git add -A
+# Step 4: Stage files and report effective commit scope
+if [[ "$PRIMARY_SCOPE_DECLARED" == "true" ]]; then
+  echo ">> git add (scoped) && git commit"
+  git add -- "${FILES[@]}"
+  # Stage generated companion files if they have changes
+  for companion in eslint.config.mjs; do
+    if [[ -f "$companion" ]] && ! git diff --quiet -- "$companion" 2>/dev/null; then
+      git add -- "$companion"
+    fi
+  done
+  # Stage locales/strings if yarn localize changed them (already git-added by
+  # yarn localize in some repos, but ensure they're staged)
+  if git diff --quiet --cached -- src/locales/strings 2>/dev/null; then
+    git diff --quiet -- src/locales/strings 2>/dev/null || git add -- src/locales/strings/ 2>/dev/null || true
+  fi
+else
+  echo ">> git add -A && git commit"
+  git add -A
+fi
 
 # Graduate files from eslint warning-override list if the repo has the script
 if node -e "process.exit(require('./package.json').scripts?.['update-eslint-warnings'] ? 0 : 1)" 2>/dev/null; then
@@ -267,7 +283,7 @@ if [[ ${#LINT_FILES[@]} -gt 0 && -x ./node_modules/.bin/jest ]]; then
       echo ">> Auto-generated companion files staged:"
       echo "$SNAP_CHANGES"
     fi
-    git add -A
+    git add -- $SNAP_CHANGES
     git commit --amend --no-edit --no-verify
   else
     echo ">> No snapshot changes"