refactor(auto-code-quality): replace Stop hooks with /cq skill

The 3 Stop hooks (format-on-stop, lint-file, advisory-test-runner) caused
race conditions with background agents, fired too frequently during
orchestration pauses, and produced lint results as passive context that
Claude couldn't act on.

Replace them with:
- /cq skill — Claude runs format, lint (auto-fix), and tests explicitly
- quality-gate.py — lightweight Stop hook that prompts /cq when needed
- task-tracker.py — tracks active background tasks to avoid conflicts

The gate is background-task-aware and self-cleaning (deletes temp files
on block to prevent loops).

Author: AnExiledDev

container/.devcontainer/AGENTS.md

@@ -50,7 +50,7 @@ Declared in `settings.json` under `enabledPlugins`, auto-activated on start:
 - **skill-engine** — 23 general coding skills + auto-suggestion
 - **spec-workflow** — 3 spec lifecycle skills (`/spec`, `/build`, `/specs`) + spec-reminder hook
 - **session-context** — Git state injection, TODO harvesting, commit reminders
-- **auto-code-quality** — Auto-format + auto-lint + advisory test runner
+- **auto-code-quality** — File tracking, syntax validation, `/cq` quality gate (format + lint + test on demand)
 - **workspace-scope-guard** — Blocks writes outside working directory
 - **dangerous-command-blocker** — Blocks destructive bash commands
 - **protected-files-guard** — Blocks edits to secrets/lock files

container/.devcontainer/CHANGELOG.md

@@ -40,6 +40,12 @@
 - **Cross-references added** — before-you-install, accessing-services, troubleshooting, and devcontainer-cli pages now link to the Windows networking guide
 - **Agent-browser CDP troubleshooting** — new troubleshooting section for host Chrome connection issues (localhost vs host.docker.internal, Chrome version requirements, port exposure)
 
+### Code Quality
+
+- **Replaced auto-format/lint/test Stop hooks with `/cq` skill** — the three Stop hooks (`format-on-stop.py`, `lint-file.py`, `advisory-test-runner.py`) that ran automatically on every stop are replaced by a single `/cq` skill that Claude invokes explicitly. Eliminates race conditions with background agents, stops firing during orchestration pauses, and lets Claude act on lint/test results instead of ignoring passive context.
+- **New quality gate Stop hook** — lightweight `quality-gate.py` (~1ms) checks whether files were edited and no background tasks are running, then blocks the stop with a prompt to run `/cq`. Deletes temp files on block to prevent loops.
+- **New task tracker hooks** — `task-tracker.py` handles `TaskCreated`/`TaskCompleted` events to maintain an active-task count. The quality gate skips blocking while tasks are running, preventing format/lint conflicts with background agents.
+
 ### CI
 
 - **Canary pre-release publishing** — every push to `staging` that touches `container/` now auto-publishes a canary build to npm. Install with `npm i @coredirective/cf-container@canary` to try unreleased changes. Versions use the format `{version}-staging.{sha7}`.

container/.devcontainer/README.md

@@ -218,6 +218,21 @@ claude --resume               # Resume previous session
 | `codex` | OpenAI Codex CLI terminal coding agent |
 | `hermes` | Nous Research Hermes Agent CLI (run `hermes setup` on first use) |
 
+### Windows Host Chrome CDP
+
+For Hermes, Vercel agent-browser, Codex, or Claude Code to control Chrome running on a Windows host, run this from an Administrator PowerShell at the repository root:
+
+```powershell
+.\.devcontainer\scripts\start-hermes-chrome.ps1
+```
+
+The devcontainer uses `HERMES_CDP_ENDPOINT=http://192.168.65.254:9223` for Docker Desktop. Verify the current host IPv4 from inside the container:
+
+```bash
+CDP_HOST=$(getent ahostsv4 host.docker.internal | awk 'NR==1 {print $1}')
+curl http://$CDP_HOST:9223/json/version
+```
+
 ### Code Intelligence
 | Tool | Description |
 |------|-------------|
@@ -335,7 +350,7 @@ CodeForge includes custom devcontainer features. Any feature can be disabled by
 
 ### auto-code-quality
 
-Combined auto-formatter, auto-linter, and advisory test runner plugin at `plugins/devs-marketplace/plugins/auto-code-quality/`. Three-phase pipeline: collect edited files (PostToolUse), batch format + lint (Stop), and advisory test runner (Stop). Supports all languages from the former auto-formatter + auto-linter plugins. Replaces the separate `auto-formatter` and `auto-linter` plugins.
+Code quality plugin at `plugins/devs-marketplace/plugins/auto-code-quality/`. Tracks edited files (PostToolUse), validates data file syntax instantly, tracks background tasks (TaskCreated/Completed), and gates stops with a lightweight check — if files were edited and no tasks are running, prompts Claude to run the `/cq` skill for formatting, linting (with auto-fix), and affected test execution. Supports Python, JS/TS, Go, Shell, Rust, Markdown, YAML, TOML, and Dockerfiles.
 
 ## Alias Management
 

container/.devcontainer/plugins/devs-marketplace/.claude-plugin/marketplace.json

@@ -84,7 +84,7 @@
 		},
 		{
 			"name": "auto-code-quality",
-			"description": "Self-contained code quality: auto-format + auto-lint edited files (Ruff/Black, Biome, gofmt, shfmt, dprint, rustfmt, Pyright, ShellCheck, go vet, hadolint, clippy)",
+			"description": "Code quality with /cq skill: file tracking, syntax validation, background-task-aware quality gate, on-demand format + lint + test (Ruff, Biome, gofmt, shfmt, dprint, rustfmt, Pyright, ShellCheck, go vet, hadolint, clippy)",
 			"version": "1.0.0",
 			"source": "./plugins/auto-code-quality",
 			"category": "development",

container/.devcontainer/plugins/devs-marketplace/plugins/auto-code-quality/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "auto-code-quality",
-	"description": "Self-contained code quality plugin: collects edited files, batch-formats at Stop (Ruff/Black for Python, gofmt for Go, Biome for JS/TS/CSS/JSON/GraphQL/HTML, shfmt for Shell, dprint for Markdown/YAML/TOML/Dockerfile, rustfmt for Rust), batch-lints at Stop (Pyright + Ruff for Python, Biome for JS/TS/CSS/GraphQL, ShellCheck for Shell, go vet for Go, hadolint for Dockerfile, clippy for Rust), and validates JSON/JSONC/YAML/TOML syntax on edit",
+	"description": "Code quality plugin: collects edited files on edit, validates JSON/JSONC/YAML/TOML syntax instantly, tracks background tasks, and gates stops with a /cq skill prompt — format, lint, and test on demand instead of automatically",
 	"author": {
 		"name": "AnExiledDev"
 	}

container/.devcontainer/plugins/devs-marketplace/plugins/auto-code-quality/README.md

@@ -1,18 +1,20 @@
 # auto-code-quality
 
-Self-contained Claude Code plugin that automatically formats and lints edited files. Drop it into any Claude Code plugin marketplace and enable it — no other plugins required.
+Claude Code plugin that tracks edited files and runs code quality checks on demand via the `/cq` skill. Drop it into any Claude Code plugin marketplace and enable it — no other plugins required.
 
 ## What It Does
 
-Three-phase pipeline that runs transparently during your Claude Code session:
+Two-phase pipeline with an explicit quality gate:
 
-1. **Collect** (PostToolUse on Edit/Write) — Records which files Claude edits
-2. **Format** (Stop hook) — Batch-formats all edited files when Claude finishes responding
-3. **Lint** (Stop hook) — Batch-lints all edited files and surfaces warnings as context
+1. **Track** (PostToolUse on Edit/Write) — Records which files Claude edits, validates data file syntax instantly
+2. **Gate** (Stop hook) — Lightweight check: if files were edited and no background tasks are running, blocks the stop and prompts Claude to run `/cq`
+3. **Quality** (`/cq` skill) — Claude formats, lints (with auto-fix), and runs affected tests on all edited files
 
-Additionally validates JSON, JSONC, YAML, and TOML syntax immediately after each edit.
+The `/cq` skill can also be invoked manually at any time during a session.
 
-All phases are non-blocking. Missing tools are silently skipped. The plugin always exits cleanly — it will never interrupt Claude.
+### Why a skill instead of automatic hooks?
+
+Previous versions ran formatters, linters, and test runners as Stop hooks. This caused issues with background agents (race conditions on file writes), fired too frequently during orchestration pauses, and produced lint results as passive context that was often ignored. The `/cq` skill runs explicitly — Claude can act on results, fix issues, and re-run checks.
 
 ## Required Tools
 
@@ -21,7 +23,6 @@ Install the tools for the languages you work with. Everything is optional — th
 | Language | Formatter | Linter(s) | Install |
 |----------|-----------|-----------|---------|
 | Python | [ruff](https://docs.astral.sh/ruff/) | [pyright](https://github.com/microsoft/pyright), ruff check | `pip install ruff` / `npm i -g pyright` |
-| Python (fallback) | [black](https://github.com/psf/black) | — | `pip install black` |
 | Go | gofmt (bundled with Go) | go vet (bundled with Go) | [Install Go](https://go.dev/dl/) |
 | JS/TS/CSS/GraphQL/HTML | [biome](https://biomejs.dev/) | biome lint | `npm i -D @biomejs/biome` or `npm i -g @biomejs/biome` |
 | Shell | [shfmt](https://github.com/mvdan/sh) | [shellcheck](https://github.com/koalaman/shellcheck) | `brew install shfmt shellcheck` |
@@ -48,6 +49,28 @@ Biome is resolved in this order:
 1. Project-local: walks up from the edited file looking for `node_modules/.bin/biome`
 2. Global: checks PATH via `which biome`
 
+## Usage
+
+### Automatic (quality gate)
+
+Just work normally. When Claude stops after editing files:
+
+1. The quality gate checks for edited files and active background tasks
+2. If files were edited and no tasks are running, it blocks the stop
+3. Claude runs `/cq` automatically — formats, lints, tests, fixes issues
+4. Claude stops cleanly on the second attempt (temp files cleaned up)
+
+### Manual
+
+Type `/cq` at any point to run quality checks on all files edited so far in the session.
+
+### With background tasks
+
+The quality gate is background-task-aware:
+- While tasks are running, the gate stays silent (no blocking)
+- Once all tasks complete and Claude stops, the gate activates
+- This prevents race conditions from formatting files that agents are still writing
+
 ## Installation
 
 ### CodeForge DevContainer
@@ -85,60 +108,97 @@ You edit a file (Edit/Write tool)
   │
   ├─→ collect-edited-files.py    Appends path to temp files
   └─→ syntax-validator.py        Validates JSON/YAML/TOML syntax immediately
-       │
-       │  ... Claude keeps working ...
-       │
+
+Background task spawned (TaskCreated)
+  └─→ task-tracker.py            Records task as active
+
+Background task done (TaskCompleted)
+  └─→ task-tracker.py            Removes task from active list
+
 Claude stops responding (Stop event)
-  │
-  ├─→ format-on-stop.py          Reads temp file, formats each file by extension
-  └─→ lint-file.py               Reads temp file, lints each file, injects warnings
+  └─→ quality-gate.py            Checks tasks + edited files
+       │
+       ├─ Tasks active?  → skip (exit 0)
+       ├─ No edits?      → skip (exit 0)
+       └─ Edits found    → block stop → Claude runs /cq
+                                → /cq formats, lints, tests
+                                → cleans up temp files
+                                → Claude stops again → gate exits clean
 ```
 
 ### Temp File Convention
 
-Edited file paths are stored in session-scoped temp files:
-- `/tmp/claude-cq-edited-{session_id}` — consumed by the formatter
-- `/tmp/claude-cq-lint-{session_id}` — consumed by the linter
+Session-scoped temp files in `/tmp/`:
 
-Both are always cleaned up after processing (even on error).
+| File | Purpose | Written by | Read by |
+|------|---------|------------|---------|
+| `claude-cq-edited-{session_id}` | Edited file paths (format + test) | collect-edited-files.py | quality-gate.py, /cq skill |
+| `claude-cq-lint-{session_id}` | Edited file paths (lint) | collect-edited-files.py | /cq skill |
+| `claude-active-tasks-{session_id}` | Active background task IDs | task-tracker.py | quality-gate.py |
+
+All temp files are cleaned up after processing (by the gate and/or the skill).
+
+### Loop Prevention
+
+The quality gate deletes the edited-files temp file when it blocks. On the second stop (after `/cq` runs), the temp file is gone — the gate exits clean. The `/cq` skill also cleans up temp files as a safety net.
 
 ### Timeouts
 
 | Hook | Timeout |
 |------|---------|
 | File collection | 3s |
 | Syntax validation | 5s |
-| Batch formatting | 15s total |
-| Batch linting | 60s total |
-| Individual tool | 10-12s each |
+| Task tracking | 3s |
+| Quality gate | 3s |
+
+The `/cq` skill has no timeout — it runs as a normal Claude conversation turn.
+
+## Disabling
+
+### Disable the entire plugin
+
+Remove from `enabledPlugins` in your settings.
+
+### Disable individual hooks
+
+Add the script name (without `.py`) to the `disabled` array in `~/.claude/disabled-hooks.json`:
+
+```json
+{
+  "disabled": ["quality-gate"]
+}
+```
+
+Available hook names: `collect-edited-files`, `syntax-validator`, `task-tracker`, `quality-gate`
 
 ## Conflict Warning
 
 This plugin bundles functionality that may overlap with other plugins. If you're using any of the following, **disable them** before enabling this plugin to avoid duplicate processing:
 
-- `auto-formatter` — formatting is included here
-- `auto-linter` — linting is included here
+- `auto-formatter` — formatting is included in `/cq`
+- `auto-linter` — linting is included in `/cq`
 - `code-directive` `collect-edited-files.py` hook — file collection is included here
 
-All pipelines use the `claude-cq-*` temp file prefix, so enabling both won't corrupt data — but files would be formatted and linted twice.
-
 ## Plugin Structure
 
 ```
 auto-code-quality/
 ├── .claude-plugin/
 │   └── plugin.json              # Plugin metadata
 ├── hooks/
-│   └── hooks.json               # Hook registrations (PostToolUse + Stop)
+│   └── hooks.json               # Hook registrations
 ├── scripts/
 │   ├── collect-edited-files.py  # File path collector (PostToolUse)
 │   ├── syntax-validator.py      # JSON/YAML/TOML validator (PostToolUse)
-│   ├── format-on-stop.py        # Batch formatter (Stop)
-│   └── lint-file.py             # Batch linter (Stop)
+│   ├── task-tracker.py          # Background task counter (TaskCreated/Completed)
+│   └── quality-gate.py          # Stop gate — prompts /cq if needed (Stop)
+├── skills/
+│   └── cq/
+│       └── SKILL.md             # /cq skill definition
 └── README.md                    # This file
 ```
 
 ## Requirements
 
 - Python 3.11+ (for `tomllib` support in syntax validation; older Python skips TOML)
-- Claude Code with plugin hook support
+- Claude Code with plugin hook support and skill support

container/.devcontainer/plugins/devs-marketplace/plugins/auto-code-quality/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-	"description": "Self-contained code quality: file collection on edit, syntax validation, batch formatting + linting at stop",
+	"description": "Code quality: file collection on edit, syntax validation, task tracking, and /cq quality gate at stop",
 	"hooks": {
 		"PostToolUse": [
 			{
@@ -18,23 +18,35 @@
 				]
 			}
 		],
-		"Stop": [
+		"TaskCreated": [
 			{
 				"hooks": [
 					{
 						"type": "command",
-						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/format-on-stop.py",
-						"timeout": 15
-					},
+						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/task-tracker.py",
+						"timeout": 3
+					}
+				]
+			}
+		],
+		"TaskCompleted": [
+			{
+				"hooks": [
 					{
 						"type": "command",
-						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/lint-file.py",
-						"timeout": 60
-					},
+						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/task-tracker.py",
+						"timeout": 3
+					}
+				]
+			}
+		],
+		"Stop": [
+			{
+				"hooks": [
 					{
 						"type": "command",
-						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/advisory-test-runner.py",
-						"timeout": 20
+						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/quality-gate.py",
+						"timeout": 3
 					}
 				]
 			}