v2.8.27

.agent/skills/db-version-rift/SKILL.md

@@ -0,0 +1,58 @@
+# Database Version Rift Skill
+
+## Description
+
+This skill maps critical differences between MySQL and MariaDB versions to help developers implement cross-compatible diagnostics in MySQLTuner.
+
+## Replication Commands
+
+| Feature | MySQL < 8.0.22 / MariaDB < 10.5 | MySQL >= 8.0.22 | MariaDB >= 10.5 |
+| :--- | :--- | :--- | :--- |
+| **Show Slave Status** | `SHOW SLAVE STATUS` | `SHOW REPLICA STATUS` (Preferred) | `SHOW REPLICA STATUS` (Preferred) |
+| **Show Slave Hosts** | `SHOW SLAVE HOSTS` | `SHOW REPLICA HOSTS` | `SHOW REPLICA HOSTS` |
+
+**Strategy:**
+Detect version first. If version >= breakpoint, try `REPLICA`, fall back to `SLAVE` if error or empty (though strictly version check is safer).
+
+## Authentication & Security
+
+| Feature | MySQL 5.7 / MariaDB | MySQL 8.0+ |
+| :--- | :--- | :--- |
+| **PASSWORD() function**| Available | **REMOVED** (Use SHA2 functions or app-side hashing) |
+| **User table** | `mysql.user` (authentication_string since 5.7) | `mysql.user` (authentication_string) |
+
+**Strategy:**
+For password checks in MySQL 8.0+, do strictly SQL-based checks (e.g., length of auth string) or avoid logic that depends on hashing input strings via SQL.
+
+## Information Schema Differences
+
+### `information_schema.TABLES`
+
+- Usually stable, but check `Data_free` interpretation across engines.
+
+### `performance_schema`
+
+- **MySQL 5.6+**: Defaults enabled (mostly).
+- **MariaDB 10.0+**: Defaults varying.
+- **Check**: Always verify `performance_schema = ON` before querying tables.
+
+## System Variables (Renames)
+
+| Legacy Name | Modern Name (MySQL 8.0+) | Note |
+| :--- | :--- | :--- |
+| `tx_isolation` | `transaction_isolation` | Check both or `||` them. |
+| `query_cache_size` | *Removed* | Removed in MySQL 8.0 |
+
+**Strategy:**
+Use the `mysqltuner.pl` valid variable abstraction or check for existence before using.
+
+## MariaDB vs MySQL Divergence
+
+- **Thread Pool**:
+  - **MariaDB**: Built-in, specific vars (`thread_pool_size`, `thread_pool_oversubscribe`).
+  - **MySQL**: Enterprise only or Percona specific.
+  - **Action**: Check `version_comment` or `version` string for "MariaDB" before recommending thread pool settings.
+
+- **Aria Engine**:
+  - Specific to MariaDB (replacement for MyISAM for system tables).
+  - Don't tune `aria_pagecache_buffer_size` on Oracle MySQL.

.agent/skills/legacy-perl-patterns/SKILL.md

@@ -0,0 +1,98 @@
+# Legacy Perl Patterns Skill
+
+## Description
+
+This skill provides guidelines and patterns for writing Perl code that maintains backward compatibility with older Perl versions (down to 5.8) as required by the MySQLTuner project constitution.
+
+## Anti-Patterns (Avoid)
+
+### 1. `say` (Perl 5.10+)
+
+**Wrong:**
+
+```perl
+use feature 'say';
+say "Hello";
+```
+
+**Right:**
+
+```perl
+print "Hello\n";
+```
+
+### 2. `state` variables (Perl 5.10+)
+
+**Wrong:**
+
+```perl
+use feature 'state';
+sub foo {
+    state $x = 0;
+    $x++;
+}
+```
+
+**Right:**
+
+```perl
+{
+    my $x = 0;
+    sub foo {
+        $x++;
+    }
+}
+```
+
+### 3. Defined-or operator `//` (Perl 5.10+)
+
+**Wrong:**
+
+```perl
+my $a = $b // $c;
+```
+
+**Right:**
+
+```perl
+my $a = defined($b) ? $b : $c;
+```
+
+### 4. `given` / `when` (Switch statements)
+
+**Wrong:**
+
+```perl
+given ($foo) { when(1) { ... } }
+```
+
+**Right:**
+
+```perl
+if ($foo == 1) { ... }
+elsif ($foo == 2) { ... }
+```
+
+## Safe Patterns (Recommended)
+
+### 1. Three-argument `open`
+
+Always use the 3-arg form of open for safety, but check support if targeting extremely old perl (pre-5.6), though 5.8 is our floor.
+
+```perl
+open(my $fh, '<', $filename) or die "Cannot open $filename: $!";
+```
+
+### 2. Modular compatibility
+
+Avoid `use Module::Name` if the module wasn't core in 5.8.
+Check `corelist` if unsure.
+Example: `Time::HiRes` is core since 5.8.
+
+### 3. Regex
+
+Avoid 5.10+ regex extensions (e.g. named capture groups `(?<name>...)` unless you are sure). Use standard capturing parentheses `(...)`.
+
+## Validation
+
+Always test syntax with a lower version of perl if available, or rely on strict `make test` environment containers that might emulate older setups.

.agent/workflows/compliance-sentinel.md

@@ -0,0 +1,54 @@
+---
+description: Automated audit to enforce project constitution rules
+---
+
+# Compliance Sentinel
+
+This workflow acts as a static analysis guardrail to ensure "Constitution" compliance.
+
+## 1. Core Check: Single File Architecture
+
+Ensure no additional Perl modules (.pm) have been added to the root or lib dirs intended for distribution.
+
+```bash
+if [ $(find . -maxdepth 2 -name "*.pm" | wc -l) -gt 0 ]; then
+  echo "FAIL: No .pm files allowed. Architecture must remain Single File."
+  exit 1
+fi
+```
+
+## 2. Core Check: Zero Dependency (Standard Core Only)
+
+Scan for non-core CPAN modules.
+
+```bash
+# Allow-list (examples of standard modules)
+# strict, warnings, Getopt::Long, File::Basename, Data::Dumper, POSIX, etc.
+# Grep for 'use' and manually review or verify against `corelist`.
+grep "^use " mysqltuner.pl | sort | uniq
+```
+
+## 3. Core Check: Syscall Protection
+
+Verify that system calls are safe.
+
+```bash
+# Look for potential unsafe system calls (qx, ``, system)
+grep -nE "qx/|`|system\(" mysqltuner.pl
+# Manual Review: Ensure each is wrapped or checked.
+```
+
+## 4. Changelog Compliance
+
+Verify the format of the latest Changelog entries.
+
+```bash
+head -n 20 Changelog
+# Must follow:
+# X.Y.Z YYYY-MM-DD
+# - type: description
+```
+
+## 5. Execution
+
+Run these checks before any major commit or release.

.agent/workflows/docker-clean.md

@@ -0,0 +1,29 @@
+---
+description: /docker-clean
+---
+
+---
+
+description: Reclaim disk space by removing unused containers and images
+---
+
+1. **Check Current Usage**:
+   - See how much space Docker is using.
+   // turbo
+   - Run `docker system df`
+
+2. **Run Prune**:
+   - ⚠️ **WARNING**: This will remove all stopped containers and unused images!
+   - Remove all stopped containers, unused networks, and dangling images.
+   // turbo
+   - Run `docker system prune -a`
+
+3. **Verify Space Reclaimed**:
+   - Check the new disk usage.
+   // turbo
+   - Run `docker system df`
+
+4. **Pro Tips**:
+   - Add `--volumes` to also delete unused volumes (DATA LOSS WARNING!).
+   - To remove only dangling images: `docker image prune`.
+   - Set up automatic cleanup: add `"log-opts": {"max-size": "10m"}` to Docker daemon config.

.agent/workflows/release-preflight.md

@@ -0,0 +1,49 @@
+---
+description: Pre-flight checks before triggering a git-flow release
+---
+
+# Release Preflight Workflow
+
+Ensure consistency across versioning artifacts before cutting a release.
+
+## 1. Extract Versions
+
+```bash
+# 1. mysqltuner.pl internal version
+SCRIPT_VER=$(grep "mysqltuner.pl v" mysqltuner.pl | head -n 1 | awk '{print $2}' | sed 's/v//')
+
+# 2. CURRENT_VERSION.txt
+TXT_VER=$(cat CURRENT_VERSION.txt)
+
+# 3. Changelog latest version
+LOG_VER=$(head -n 1 Changelog | awk '{print $1}')
+```
+
+## 2. Validate Consistency
+
+All three versions must match.
+
+```bash
+if [ "$SCRIPT_VER" == "$TXT_VER" ] && [ "$TXT_VER" == "$LOG_VER" ]; then
+    echo "SUCCESS: Versions match ($SCRIPT_VER)."
+else
+    echo "FAIL: Version Mismatch!"
+    echo "Script:    $SCRIPT_VER"
+    echo "Txt:       $TXT_VER"
+    echo "Changelog: $LOG_VER"
+    exit 1
+fi
+```
+
+## 3. Smoke Test
+
+Run the primary test suite to ensure the build isn't broken.
+
+```bash
+# Assuming make test exists and runs the suite
+make test
+```
+
+## 4. Proceed to Release
+
+If all checks pass, proceed with `/git-flow`.

.agent/workflows/snapshot-to-test.md

@@ -0,0 +1,83 @@
+---
+description: Transform a running production issue into a reproducible test case
+---
+
+# Snapshot to Test Workflow
+
+This workflow helps capture the state of a running database (where a bug is observed) and converts it into a standalone Perl test case for TDD.
+
+## 1. Context Acquisition
+
+Identify the target container or host where the issue is reproducible.
+
+```bash
+# Example: Define target
+TARGET_CONTAINER="mysql_8_0" 
+```
+
+## 2. Capture Variables and Status
+
+Extract the raw data required by MySQLTuner to mock the environment.
+
+```bash
+# Extract Global Variables
+docker exec -i $TARGET_CONTAINER mysql -NBe "SHOW GLOBAL VARIABLES" > /tmp/vars.txt
+
+# Extract Global Status
+docker exec -i $TARGET_CONTAINER mysql -NBe "SHOW GLOBAL STATUS" > /tmp/status.txt
+```
+
+## 3. Generate Test Skeleton
+
+Create a new test file in `tests/` (e.g., `tests/repro_issue_XXX.t`).
+
+Use the following template:
+
+```perl
+#!/usr/bin/env perl
+use strict;
+use warnings;
+use Test::More;
+use Data::Dumper;
+
+# 1. Load MySQLTuner logic
+# (Adjust path if needed to load specific subroutines)
+require 'mysqltuner.pl';
+
+# 2. Mock Data
+# Insert data captured from /tmp/vars.txt and /tmp/status.txt
+my %mock_variables = (
+    # ... content from vars.txt formatted as hash ...
+    'version' => '8.0.32',
+    'innodb_buffer_pool_size' => '1073741824',
+);
+
+my %mock_status = (
+    # ... content from status.txt formatted as hash ...
+    'Uptime' => '3600',
+    'Questions' => '500',
+);
+
+# 3. Setup Environment
+# Overlay mock data onto the script's global hashes
+*main::myvar = \%mock_variables;
+*main::mystat = \%mock_status;
+
+# 4. Execute Logic
+# Call the specific subroutine under test
+# e.g., setup_innodb_buffer_pool();
+
+# 5. Assertions
+# Verify the expected behavior (bug reproduction or fix verification)
+ok(1, "Placeholder assertion");
+
+done_testing();
+```
+
+## 4. Run and Refine
+
+Run the test to confirm it fails (if reproducing a bug) or passes (if verifying logic).
+
+```bash
+prove tests/repro_issue_XXX.t
+```

CURRENT_VERSION.txt

@@ -1 +1 @@
-2.8.25
+2.8.27