[codex] chore(quality): add AI-assisted quality gates

.github/workflows/quality.yml

@@ -0,0 +1,122 @@
+name: Quality
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/quality.yml"
+      - ".gitignore"
+      - "AGENTS.md"
+      - "addons/mimic/**/*.gd"
+      - "addons/mimic/**/*.res"
+      - "addons/mimic/**/*.tres"
+      - "addons/mimic/**/*.tscn"
+      - "addons/mimic/plugin.cfg"
+      - "CLAUDE.md"
+      - "export_presets.cfg"
+      - "examples/**/*.gd"
+      - "examples/**/*.res"
+      - "examples/**/*.tres"
+      - "examples/**/*.tscn"
+      - "project.godot"
+      - "test/**/*.gd"
+      - "test/**/*.res"
+      - "test/**/*.tres"
+      - "test/**/*.tscn"
+      - "tools/.gdignore"
+      - "tools/*.ps1"
+      - "tools/**/*.ps1"
+      - "tools/quality/**"
+      - "README.md"
+      - "docs/guides/ai_quality_workflow.md"
+      - "mkdocs.yml"
+  pull_request:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/quality.yml"
+      - ".gitignore"
+      - "AGENTS.md"
+      - "addons/mimic/**/*.gd"
+      - "addons/mimic/**/*.res"
+      - "addons/mimic/**/*.tres"
+      - "addons/mimic/**/*.tscn"
+      - "addons/mimic/plugin.cfg"
+      - "CLAUDE.md"
+      - "export_presets.cfg"
+      - "examples/**/*.gd"
+      - "examples/**/*.res"
+      - "examples/**/*.tres"
+      - "examples/**/*.tscn"
+      - "project.godot"
+      - "test/**/*.gd"
+      - "test/**/*.res"
+      - "test/**/*.tres"
+      - "test/**/*.tscn"
+      - "tools/.gdignore"
+      - "tools/*.ps1"
+      - "tools/**/*.ps1"
+      - "tools/quality/**"
+      - "README.md"
+      - "docs/guides/ai_quality_workflow.md"
+      - "mkdocs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  static_quality:
+    name: Static Quality
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: tools/quality/package-lock.json
+
+      - name: Setup Python
+        id: setup-python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Cache bootstrapped quality tools
+        uses: actions/cache@v5
+        with:
+          path: tools/.bin
+          key: quality-tools-${{ runner.os }}-python-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('tools/quality.ps1', 'tools/quality/gdstyle.toml', 'tools/quality/gdcruiser.json', 'tools/quality/requirements_quality.txt') }}
+
+      - name: Run Mimic quality checks
+        shell: pwsh
+        run: ./tools/quality.ps1 -BootstrapTools
+
+  godot_regression:
+    name: Godot Regression
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Godot
+        uses: chickensoft-games/setup-godot@v2
+        with:
+          version: "4.6.3"
+          use-dotnet: false
+          include-templates: false
+
+      - name: Verify Godot setup
+        shell: pwsh
+        run: godot --version
+
+      - name: Run Godot regression checks
+        shell: pwsh
+        run: ./tools/verify.ps1 -SkipQuality

.gitignore

@@ -3,6 +3,8 @@
 /android/
 .vscode/settings.json
 /test/.output/
+/tools/.bin/
+/tools/quality/node_modules/
 __pycache__/
 
 # Generated documentation and export artifacts

AGENTS.md

@@ -20,7 +20,7 @@ Consistency updates: When changing public behavior, public API, Project Settings
 
 Godot MCP: Use the repo-local `.mcp.json` server named `godot` when an MCP-capable agent needs to query Godot, launch the editor, run the project, inspect project info, or capture debug output. The server is configured to run `npx -y @coding-solo/godot-mcp@latest` with `GODOT_PATH` set to `C:\Programming_Files\Godot\Godot_v4.6.3-stable_win64.exe\Godot_v4.6.3-stable_win64.exe`. Keep MCP configuration local to this repository unless explicitly requested otherwise.
 
-Testing and automation: Treat tests as regression guardrails for AI-assisted changes, not as a mandatory TDD ceremony. Add or update GUT tests in `res://test/unit/` when changing public Mimic behavior, fixing bugs, or touching connection lifecycle, project settings, editor plugin behavior, networking helpers, or example flows that should stay stable. For meaningful feature changes, behavior changes, and risky refactors, run `powershell -NoProfile -ExecutionPolicy Bypass -File tools/verify.ps1` before final response; for especially risky work, run it before and after the change to catch regressions early. Do not add tests for docs-only edits, comments-only edits, or mechanical formatting with no behavior impact. Use `tools/run_two_instances.ps1` for explicit local ENet server/client smoke coverage; prefer these deterministic CLI scripts over MCP as the source of truth for CI-style verification.
+Testing and automation: Treat tests as regression guardrails for AI-assisted changes, not as a mandatory TDD ceremony. Add or update GUT tests in `res://test/unit/` when changing public Mimic behavior, fixing bugs, or touching connection lifecycle, project settings, editor plugin behavior, networking helpers, or example flows that should stay stable. For meaningful feature changes, behavior changes, and risky refactors, run `powershell -NoProfile -ExecutionPolicy Bypass -File tools/verify.ps1` before final response; for especially risky work, run it before and after the change to catch regressions early. Use `powershell -NoProfile -ExecutionPolicy Bypass -File tools/quality.ps1` for the fast AI-focused quality gate: Mimic policy and public API documentation checks, PowerShell syntax checks, lockfile-backed `jscpd@4.2.4` duplicate-code detection with a committed baseline, optional hash-locked `gdcruiser==1.7.0` dependency architecture checks, and optional checksum-verified `gdstyle v0.1.4` diagnostics. Do not add tests for docs-only edits, comments-only edits, or mechanical formatting with no behavior impact. Use `tools/run_two_instances.ps1` for explicit local ENet server/client smoke coverage; prefer these deterministic CLI scripts over MCP as the source of truth for CI-style verification.
 
 Git commits: Use Conventional Commits in type(scope): summary form, such as feat(mimic): add connection logging.
 
@@ -84,6 +84,12 @@ test/integration/mimic_connection_probe.gd: Explicit server/client probe script
 tools/: Local PowerShell automation entry points.
 tools/godot.ps1: Repo-local Godot CLI wrapper with Godot 4.6.3 fallback.
 tools/verify.ps1: Full local verification pass for import, unit tests, startup smoke, ENet explicit/auto-connect smoke, and WebSocket smoke.
+tools/quality.ps1: Fast AI-focused quality gate for Mimic policy and public API documentation checks, PowerShell syntax checks, duplicate-code detection, dependency architecture checks, and GDScript style diagnostics.
+tools/quality/: Static quality tool configuration kept out of Godot's resource scan by tools/.gdignore.
+tools/quality/jscpd_baseline.json: Committed duplicate-code baseline used by the jscpd ratchet.
+tools/quality/package.json: Local Node tool manifest for locked jscpd execution.
+tools/quality/package-lock.json: npm lockfile with integrity hashes for jscpd and its transitive dependencies.
+tools/quality/requirements_quality.txt: Hash-locked Python requirement used when bootstrapping gdcruiser.
 tools/run_two_instances.ps1: Explicit ENet/WebSocket server/client and auto-connect smoke test runner.
 tools/mkdocs_hooks.py: MkDocs hook that generates API docs and copies SVG/PNG brand assets into the built documentation site.
 ```

CLAUDE.md

@@ -20,7 +20,7 @@ Consistency updates: When changing public behavior, public API, Project Settings
 
 Godot MCP: Use the repo-local `.mcp.json` server named `godot` when an MCP-capable agent needs to query Godot, launch the editor, run the project, inspect project info, or capture debug output. The server is configured to run `npx -y @coding-solo/godot-mcp@latest` with `GODOT_PATH` set to `C:\Programming_Files\Godot\Godot_v4.6.3-stable_win64.exe\Godot_v4.6.3-stable_win64.exe`. Keep MCP configuration local to this repository unless explicitly requested otherwise.
 
-Testing and automation: Treat tests as regression guardrails for AI-assisted changes, not as a mandatory TDD ceremony. Add or update GUT tests in `res://test/unit/` when changing public Mimic behavior, fixing bugs, or touching connection lifecycle, project settings, editor plugin behavior, networking helpers, or example flows that should stay stable. For meaningful feature changes, behavior changes, and risky refactors, run `powershell -NoProfile -ExecutionPolicy Bypass -File tools/verify.ps1` before final response; for especially risky work, run it before and after the change to catch regressions early. Do not add tests for docs-only edits, comments-only edits, or mechanical formatting with no behavior impact. Use `tools/run_two_instances.ps1` for explicit local ENet server/client smoke coverage; prefer these deterministic CLI scripts over MCP as the source of truth for CI-style verification.
+Testing and automation: Treat tests as regression guardrails for AI-assisted changes, not as a mandatory TDD ceremony. Add or update GUT tests in `res://test/unit/` when changing public Mimic behavior, fixing bugs, or touching connection lifecycle, project settings, editor plugin behavior, networking helpers, or example flows that should stay stable. For meaningful feature changes, behavior changes, and risky refactors, run `powershell -NoProfile -ExecutionPolicy Bypass -File tools/verify.ps1` before final response; for especially risky work, run it before and after the change to catch regressions early. Use `powershell -NoProfile -ExecutionPolicy Bypass -File tools/quality.ps1` for the fast AI-focused quality gate: Mimic policy and public API documentation checks, PowerShell syntax checks, lockfile-backed `jscpd@4.2.4` duplicate-code detection with a committed baseline, optional hash-locked `gdcruiser==1.7.0` dependency architecture checks, and optional checksum-verified `gdstyle v0.1.4` diagnostics. Do not add tests for docs-only edits, comments-only edits, or mechanical formatting with no behavior impact. Use `tools/run_two_instances.ps1` for explicit local ENet server/client smoke coverage; prefer these deterministic CLI scripts over MCP as the source of truth for CI-style verification.
 
 Git commits: Use Conventional Commits in type(scope): summary form, such as feat(mimic): add connection logging.
 
@@ -84,6 +84,12 @@ test/integration/mimic_connection_probe.gd: Explicit server/client probe script
 tools/: Local PowerShell automation entry points.
 tools/godot.ps1: Repo-local Godot CLI wrapper with Godot 4.6.3 fallback.
 tools/verify.ps1: Full local verification pass for import, unit tests, startup smoke, ENet explicit/auto-connect smoke, and WebSocket smoke.
+tools/quality.ps1: Fast AI-focused quality gate for Mimic policy and public API documentation checks, PowerShell syntax checks, duplicate-code detection, dependency architecture checks, and GDScript style diagnostics.
+tools/quality/: Static quality tool configuration kept out of Godot's resource scan by tools/.gdignore.
+tools/quality/jscpd_baseline.json: Committed duplicate-code baseline used by the jscpd ratchet.
+tools/quality/package.json: Local Node tool manifest for locked jscpd execution.
+tools/quality/package-lock.json: npm lockfile with integrity hashes for jscpd and its transitive dependencies.
+tools/quality/requirements_quality.txt: Hash-locked Python requirement used when bootstrapping gdcruiser.
 tools/run_two_instances.ps1: Explicit ENet/WebSocket server/client and auto-connect smoke test runner.
 tools/mkdocs_hooks.py: MkDocs hook that generates API docs and copies SVG/PNG brand assets into the built documentation site.
 ```

README.md

@@ -25,7 +25,6 @@ This project is intentionally smaller than full networking frameworks. Mimic is
 - [Mimic Or NetFox?](#mimic-or-netfox)
 - [Current Limitations](#current-limitations)
 - [Minimal Local Test](#minimal-local-test)
-- [Regression Testing And Automation](#regression-testing-and-automation)
 - [Editor Multi-Instance Testing](#editor-multi-instance-testing)
 
 ## Compatibility Policy
@@ -403,53 +402,6 @@ Expected result:
 - The second instance joins as client.
 - Connection events appear in the Godot output.
 
-## Regression Testing And Automation
-
-Mimic includes automated checks intended to keep current behavior stable as the addon evolves. These tests are regression guardrails, not a requirement to practice test-driven development before every change.
-
-Run the full local verification pass from PowerShell:
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File tools/verify.ps1
-```
-
-This uses the repo-local Godot wrapper in `tools/godot.ps1`. By default it prefers a valid `MIMIC_GODOT_PATH`, then a valid `GODOT_PATH`, then the local Godot 4.6.3 path:
-
-```text
-C:\Programming_Files\Godot\Godot_v4.6.3-stable_win64.exe\Godot_v4.6.3-stable_win64_console.exe
-```
-
-Override the executable for one run:
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File tools/verify.ps1 -GodotPath "C:\path\to\Godot.exe"
-```
-
-The verification pass does six things:
-
-- Imports project resources with Godot in headless mode.
-- Runs GUT unit regression tests from `res://test/unit/`.
-- Runs a minimal project startup probe headlessly without opening a network peer.
-- Runs a two-instance ENet explicit host/client smoke test through `res://test/integration/mimic_connection_probe.tscn`.
-- Runs a two-instance ENet `Server Then Client` smoke test.
-- Runs a two-instance WebSocket explicit host/client smoke test.
-
-Run just the unit tests:
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File tools/godot.ps1 --headless --path . -s res://addons/gut/gut_cmdln.gd -gconfig=res://.gutconfig.json -gexit
-```
-
-Run just the two-instance connection smoke test:
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File tools/run_two_instances.ps1 -Transport enet -ConnectMode explicit -Port 18910
-powershell -NoProfile -ExecutionPolicy Bypass -File tools/run_two_instances.ps1 -Transport enet -ConnectMode server_then_client -Port 18911
-powershell -NoProfile -ExecutionPolicy Bypass -File tools/run_two_instances.ps1 -Transport websocket -ConnectMode explicit -Port 18912
-```
-
-Unit tests use the vendored GUT addon in `res://addons/gut/`. Add tests when changing public Mimic behavior, fixing a bug, or touching connection/project-settings code that automated changes could easily regress later.
-
 ## Editor Multi-Instance Testing
 
 Godot can launch multiple local game instances from the editor: