claude-dev-env 2.35.0 → 4.0.0

package/bin/select-pstack-models.test.mjs

@@ -0,0 +1,378 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+    allPstackRoleRequirements,
+    selectPstackDelegation,
+} from '../scripts/select_pstack_models.mjs';
+
+const ALL_PSTACK_ROLES = [
+    'feature, refactoring',
+    'bug-fix',
+    'perf-issue',
+    'hillclimb',
+    'judgment and prose',
+    'hardest tasks',
+    'how explorer',
+    'how explainer',
+    'how critics',
+    'why investigators',
+    'why synthesizer',
+    'reflect tooling',
+    'reflect judgment, divergent, synthesizer',
+    'arena runners',
+    'arena cross-judge pool',
+    'swarm workers',
+    'architect runners',
+    'interrogate reviewers',
+];
+
+function writeHostPreferences(preferencesDirectory, host, modelsByRole) {
+    mkdirSync(preferencesDirectory, { recursive: true });
+    writeFileSync(
+        join(preferencesDirectory, 'pstack-model-preferences.' + host + '.json'),
+        JSON.stringify({ host, modelsByRole }),
+    );
+}
+
+function selectWithPreferences(preferencesDirectory, overrides) {
+    return selectPstackDelegation({
+        host: 'codex',
+        inventoryHost: 'codex',
+        role: 'feature, refactoring',
+        delegationIndex: 0,
+        availableModelIds: ['gpt-5.6-sol'],
+        confirmedSuitableModelIds: [],
+        parentFallback: {
+            isAllowed: false,
+            hasMaterialCapabilityLoss: false,
+        },
+        preferencesDirectory,
+        ...overrides,
+    });
+}
+
+test('portable policy represents every pstack role without model ids', () => {
+    assert.deepEqual(Object.keys(allPstackRoleRequirements), ALL_PSTACK_ROLES);
+    const serializedRequirements = JSON.stringify(allPstackRoleRequirements);
+    assert.doesNotMatch(serializedRequirements, /gpt-|claude-|grok-/i);
+});
+
+test('Codex preferences select every available model in a diverse panel', () => {
+    const preferencesDirectory = mkdtempSync(join(tmpdir(), 'pstack-codex-'));
+    try {
+        writeHostPreferences(preferencesDirectory, 'codex', {
+            'how critics': ['gpt-5.6-terra', 'gpt-5.6-sol', 'gpt-6-astra'],
+        });
+        const selection = selectWithPreferences(preferencesDirectory, {
+            role: 'how critics',
+            delegationIndex: 1,
+            availableModelIds: ['gpt-5.6-sol', 'gpt-6-astra', 'gpt-5.6-terra'],
+        });
+        assert.equal(selection.canDelegate, true);
+        assert.equal(selection.selectedHost, 'codex');
+        assert.equal(selection.selectionSource, 'host-preference');
+        assert.deepEqual(selection.panel.selectedModelIds, [
+            'gpt-5.6-terra',
+            'gpt-5.6-sol',
+            'gpt-6-astra',
+        ]);
+        assert.equal(selection.panel.isCrossModelDiverse, true);
+        assert.deepEqual(selection.nativeSpawnArguments, { model: 'gpt-5.6-sol' });
+        assert.equal(selection.omitNativeModelArgument, false);
+        assert.equal(selection.availabilityValidated, true);
+    } finally {
+        rmSync(preferencesDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a foreign host reads only its own saved preferences', () => {
+    const preferencesDirectory = mkdtempSync(join(tmpdir(), 'pstack-host-'));
+    try {
+        writeHostPreferences(preferencesDirectory, 'codex', {
+            'feature, refactoring': ['gpt-5.6-sol'],
+        });
+        writeHostPreferences(preferencesDirectory, 'claude', {
+            'feature, refactoring': ['confirmed-claude-model'],
+        });
+        const selection = selectWithPreferences(preferencesDirectory, {
+            host: 'claude',
+            inventoryHost: 'claude',
+            availableModelIds: ['confirmed-claude-model', 'gpt-5.6-sol'],
+        });
+        assert.equal(selection.selectedHost, 'claude');
+        assert.deepEqual(selection.nativeSpawnArguments, {
+            model: 'confirmed-claude-model',
+        });
+    } finally {
+        rmSync(preferencesDirectory, { recursive: true, force: true });
+    }
+});
+
+test('an unavailable preferred model uses a confirmed host alternative', () => {
+    const preferencesDirectory = mkdtempSync(join(tmpdir(), 'pstack-alternative-'));
+    try {
+        writeHostPreferences(preferencesDirectory, 'codex', {
+            'feature, refactoring': ['gpt-5.6-sol'],
+        });
+        const selection = selectWithPreferences(preferencesDirectory, {
+            availableModelIds: ['confirmed-current-model'],
+            confirmedSuitableModelIds: ['confirmed-current-model'],
+        });
+        assert.equal(selection.canDelegate, true);
+        assert.equal(selection.selectionSource, 'confirmed-host-alternative');
+        assert.deepEqual(selection.nativeSpawnArguments, {
+            model: 'confirmed-current-model',
+        });
+    } finally {
+        rmSync(preferencesDirectory, { recursive: true, force: true });
+    }
+});
+
+test('the arena cross-judge pool selects one model other than the parent', () => {
+    const preferencesDirectory = mkdtempSync(join(tmpdir(), 'pstack-judge-'));
+    try {
+        writeHostPreferences(preferencesDirectory, 'codex', {
+            'arena cross-judge pool': ['gpt-5.6-sol', 'gpt-6-astra'],
+        });
+        const selection = selectWithPreferences(preferencesDirectory, {
+            role: 'arena cross-judge pool',
+            parentModelId: 'gpt-5.6-sol',
+            availableModelIds: ['gpt-5.6-sol', 'gpt-6-astra'],
+        });
+        assert.equal(selection.panel.agentCount, 1);
+        assert.deepEqual(selection.nativeSpawnArguments, { model: 'gpt-6-astra' });
+    } finally {
+        rmSync(preferencesDirectory, { recursive: true, force: true });
+    }
+});
+test('the arena cross-judge prefers a real alternative over parent inheritance', () => {
+    const preferencesDirectory = mkdtempSync(join(tmpdir(), 'pstack-judge-parent-'));
+    try {
+        writeHostPreferences(preferencesDirectory, 'codex', {
+            'arena cross-judge pool': ['auto', 'confirmed-other-model'],
+        });
+        const selection = selectWithPreferences(preferencesDirectory, {
+            role: 'arena cross-judge pool',
+            parentModelId: 'current-parent-model',
+            availableModelIds: ['confirmed-other-model'],
+            parentFallback: {
+                isAllowed: true,
+                hasMaterialCapabilityLoss: false,
+            },
+        });
+        assert.deepEqual(selection.nativeSpawnArguments, {
+            model: 'confirmed-other-model',
+        });
+        assert.equal(selection.omitNativeModelArgument, false);
+    } finally {
+        rmSync(preferencesDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a same-model swarm reports its actual panel composition', () => {
+    const preferencesDirectory = mkdtempSync(join(tmpdir(), 'pstack-swarm-'));
+    try {
+        writeHostPreferences(preferencesDirectory, 'codex', {
+            'swarm workers': ['gpt-5.6-luna'],
+        });
+        const selection = selectWithPreferences(preferencesDirectory, {
+            role: 'swarm workers',
+            delegationIndex: 2,
+            panel: {
+                agentCount: 4,
+                requiresDistinctModels: false,
+            },
+            availableModelIds: ['gpt-5.6-luna'],
+        });
+        assert.equal(selection.canDelegate, true);
+        assert.equal(selection.panel.agentCount, 4);
+        assert.deepEqual(selection.panel.selectedModelIds, [
+            'gpt-5.6-luna',
+            'gpt-5.6-luna',
+            'gpt-5.6-luna',
+            'gpt-5.6-luna',
+        ]);
+        assert.equal(selection.panel.isCrossModelDiverse, false);
+        assert.deepEqual(selection.nativeSpawnArguments, { model: 'gpt-5.6-luna' });
+    } finally {
+        rmSync(preferencesDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a diversity-required panel fails without enough distinct real models', () => {
+    const preferencesDirectory = mkdtempSync(join(tmpdir(), 'pstack-diversity-'));
+    try {
+        writeHostPreferences(preferencesDirectory, 'codex', {
+            'interrogate reviewers': ['gpt-5.6-terra', 'auto', 'gpt-5.6-sol'],
+        });
+        const selection = selectWithPreferences(preferencesDirectory, {
+            role: 'interrogate reviewers',
+            availableModelIds: ['gpt-5.6-terra', 'gpt-5.6-sol'],
+        });
+        assert.equal(selection.canDelegate, false);
+        assert.equal(selection.requiresUserChoice, true);
+        assert.equal(selection.failure, 'distinct-models-unavailable');
+        assert.equal(selection.panel.isCrossModelDiverse, false);
+        assert.deepEqual(selection.nativeSpawnArguments, {});
+    } finally {
+        rmSync(preferencesDirectory, { recursive: true, force: true });
+    }
+});
+
+test('parent inheritance omits the native model argument', () => {
+    const preferencesDirectory = mkdtempSync(join(tmpdir(), 'pstack-parent-'));
+    try {
+        writeHostPreferences(preferencesDirectory, 'codex', {
+            'feature, refactoring': ['inherit-parent'],
+        });
+        const selection = selectWithPreferences(preferencesDirectory, {
+            availableModelIds: [],
+            parentFallback: {
+                isAllowed: true,
+                hasMaterialCapabilityLoss: false,
+            },
+        });
+        assert.equal(selection.canDelegate, true);
+        assert.equal(selection.selectionSource, 'parent-inheritance');
+        assert.deepEqual(selection.nativeSpawnArguments, {});
+        assert.equal(selection.omitNativeModelArgument, true);
+    } finally {
+        rmSync(preferencesDirectory, { recursive: true, force: true });
+    }
+});
+
+test('material capability loss requires a user choice before inheritance', () => {
+    const preferencesDirectory = mkdtempSync(join(tmpdir(), 'pstack-parent-loss-'));
+    try {
+        writeHostPreferences(preferencesDirectory, 'codex', {
+            'hardest tasks': ['inherit-parent'],
+        });
+        const selection = selectWithPreferences(preferencesDirectory, {
+            role: 'hardest tasks',
+            availableModelIds: [],
+            parentFallback: {
+                isAllowed: true,
+                hasMaterialCapabilityLoss: true,
+            },
+        });
+        assert.equal(selection.canDelegate, false);
+        assert.equal(selection.requiresUserChoice, true);
+        assert.equal(selection.failure, 'parent-capability-loss');
+        assert.deepEqual(selection.nativeSpawnArguments, {});
+    } finally {
+        rmSync(preferencesDirectory, { recursive: true, force: true });
+    }
+});
+
+test('inventory and confirmed alternatives must belong to the selected host', () => {
+    const preferencesDirectory = mkdtempSync(join(tmpdir(), 'pstack-inventory-'));
+    try {
+        assert.throws(
+            () => selectWithPreferences(preferencesDirectory, {
+                host: 'codex',
+                inventoryHost: 'claude',
+            }),
+            /inventory host must match selected host/,
+        );
+        assert.throws(
+            () => selectWithPreferences(preferencesDirectory, {
+                availableModelIds: ['confirmed-current-model'],
+                confirmedSuitableModelIds: ['missing-model'],
+            }),
+            /confirmed suitable models must be available/,
+        );
+    } finally {
+        rmSync(preferencesDirectory, { recursive: true, force: true });
+    }
+});
+
+test('an empty model set materializes allowed parent inheritance', () => {
+    const preferencesDirectory = mkdtempSync(join(tmpdir(), 'pstack-empty-parent-'));
+    try {
+        const selection = selectWithPreferences(preferencesDirectory, {
+            availableModelIds: [],
+            parentFallback: {
+                isAllowed: true,
+                hasMaterialCapabilityLoss: false,
+            },
+        });
+        assert.equal(selection.canDelegate, true);
+        assert.equal(selection.selectionSource, 'parent-inheritance');
+        assert.deepEqual(selection.panel.selectedModelIds, [null]);
+        assert.equal(selection.omitNativeModelArgument, true);
+        assert.deepEqual(selection.nativeSpawnArguments, {});
+    } finally {
+        rmSync(preferencesDirectory, { recursive: true, force: true });
+    }
+});
+
+test('delegation index and fallback flags require exact boundary types', () => {
+    const preferencesDirectory = mkdtempSync(join(tmpdir(), 'pstack-boundary-'));
+    try {
+        for (const invalidIndex of [undefined, Number.NaN, 0.5, -1]) {
+            assert.throws(
+                () => selectWithPreferences(preferencesDirectory, {
+                    delegationIndex: invalidIndex,
+                }),
+                /delegation index must be a non-negative integer/,
+            );
+        }
+        for (const invalidRole of ['toString', ['feature, refactoring']]) {
+            assert.throws(
+                () => selectWithPreferences(preferencesDirectory, {
+                    role: invalidRole,
+                }),
+                /role must name a portable pstack role/,
+            );
+        }
+        assert.throws(
+            () => selectWithPreferences(preferencesDirectory, {
+                parentFallback: {
+                    isAllowed: 'yes',
+                    hasMaterialCapabilityLoss: false,
+                },
+            }),
+            /parent fallback flags must be booleans/,
+        );
+        assert.throws(
+            () => selectWithPreferences(preferencesDirectory, {
+                parentFallback: {
+                    isAllowed: true,
+                },
+            }),
+            /parent fallback flags must be booleans/,
+        );
+    } finally {
+        rmSync(preferencesDirectory, { recursive: true, force: true });
+    }
+});
+
+test('an optional-diversity review panel reports repeated models', () => {
+    const preferencesDirectory = mkdtempSync(join(tmpdir(), 'pstack-review-panel-'));
+    try {
+        writeHostPreferences(preferencesDirectory, 'codex', {
+            'how critics': ['gpt-5.6-sol'],
+        });
+        const selection = selectWithPreferences(preferencesDirectory, {
+            role: 'how critics',
+            delegationIndex: 2,
+            panel: {
+                agentCount: 3,
+                requiresDistinctModels: false,
+            },
+            availableModelIds: ['gpt-5.6-sol'],
+        });
+        assert.equal(selection.canDelegate, true);
+        assert.deepEqual(selection.panel.selectedModelIds, [
+            'gpt-5.6-sol',
+            'gpt-5.6-sol',
+            'gpt-5.6-sol',
+        ]);
+        assert.equal(selection.panel.isCrossModelDiverse, false);
+    } finally {
+        rmSync(preferencesDirectory, { recursive: true, force: true });
+    }
+});

package/docs/references/team-advisor-skill.md

@@ -1,6 +1,6 @@
-# Team-Advisor Skill
+# Team-advisor skill
 
-`/team-advisor` binds one standing warm advisor for this session at the strongest reachable tier. This skill is the selected custom reproduction path for advisor behavior: it forwards explicit packets to a warm Agent/SendMessage advisor or the read-only `codex_sol_advisor.py` path across many decision points.
+`/team-advisor` binds one standing warm advisor for this session at the strongest reachable tier. It sends explicit packets to a warm Agent/SendMessage advisor or the read-only `codex_astra_advisor.py` helper.
 
 ## Refs
 
@@ -17,4 +17,4 @@ Follow the call rules in `advisor-tool.md` (orientation first, then consult befo
 
 ## Selected path
 
-`/team-advisor` is the repository's advisor implementation. It provides explicit first-consult packets, delta consults, a standing warm reviewer, an in-session Sol spawn on Codex, and a read-only Sol CLI option.
+`/team-advisor` is the repository's advisor implementation. It provides explicit first-consult packets, delta consults, a standing warm reviewer, an in-session Astra spawn on Codex, and a read-only Astra CLI option.

package/hooks/hooks_constants/tool_names.py

@@ -0,0 +1,20 @@
+"""Shared names for mutation and shell tools."""
+
+from __future__ import annotations
+
+BASH_TOOL_NAME: str = "Bash"
+POWERSHELL_TOOL_NAME: str = "PowerShell"
+WRITE_TOOL_NAME: str = "Write"
+EDIT_TOOL_NAME: str = "Edit"
+MULTI_EDIT_TOOL_NAME: str = "MultiEdit"
+APPLY_PATCH_TOOL_NAME: str = "apply_patch"
+
+ALL_BASH_AND_POWERSHELL_TOOL_NAMES: frozenset[str] = frozenset(
+    {BASH_TOOL_NAME, POWERSHELL_TOOL_NAME}
+)
+ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES: frozenset[str] = frozenset(
+    {WRITE_TOOL_NAME, EDIT_TOOL_NAME, MULTI_EDIT_TOOL_NAME}
+)
+ALL_WRITE_EDIT_MULTI_EDIT_APPLY_PATCH_TOOL_NAMES: frozenset[str] = frozenset(
+    ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES | {APPLY_PATCH_TOOL_NAME}
+)

package/hooks/validators/README.md

@@ -2,7 +2,41 @@
 
 AST-based Python style checks for code quality enforcement.
 
-The checks live in `python_style_checks.py`; the shared source-line splitting, function-discovery, and statement-classification helpers they build on live in `python_style_helpers.py`. `python_style_import_bootstrap.py` recognizes the repo's sys.path bootstrap-guard idiom so the imports-at-top check does not penalize a file for following it. `hook_timing_harness.py` measures real wall-clock time for the Write/Edit hooks `hooks.json` registers, reporting p50 and p95 over a configurable run count. `fast_save_validators.py` runs the twelve non-Mypy, non-Ruff checks in-process for the Write/Edit save-path gate, with no per-check subprocess.
+The checks live in `python_style_checks.py`. Shared source-line splitting, function discovery, and statement classification live in `python_style_helpers.py`. `python_style_import_bootstrap.py` recognizes the repo's sys.path bootstrap-guard idiom so the imports-at-top check does not penalize a file for following it. `fast_save_validators.py` runs the twelve non-Mypy, non-Ruff checks in-process for the Write/Edit save-path gate, with no per-check subprocess.
+
+## Production modules
+
+| File | Role |
+|---|---|
+| `abbreviation_checks.py` | Abbreviation and single-letter name checks |
+| `code_quality_checks.py` | Function, nesting, and file length checks |
+| `comment_checks.py` | Comment detection for the opt-in diff-aware linter |
+| `exempt_paths.py` | Shared config, test, and hook-infrastructure path exemptions |
+| `fast_save_validators.py` | In-process Write/Edit save-path validator roster |
+| `file_structure_checks.py` | File structure checks for pre-PR validation |
+| `git_checks.py` | Git and GitHub checks for pre-push review |
+| `health_check.py` | Validator availability, dependency, and version checks |
+| `hook_timing_harness.py` | Hook runtime measurement and threshold report |
+| `magic_value_checks.py` | Hardcoded magic-number checks |
+| `mypy_integration.py` | Mypy static type checking integration |
+| `output_formatter.py` | Colored, diff, progress, and JSON validator output |
+| `pr_reference_checks.py` | PR and commit reference checks in comments |
+| `project_roots.py` | Project-root resolution from a path |
+| `pyproject_config_discovery.py` | Walk-up discovery of tool pyproject tables |
+| `python_antipattern_checks.py` | Mutable defaults, bare except, and print checks |
+| `python_style_checks.py` | Import placement, decorator spacing, blank lines, and view naming |
+| `python_style_helpers.py` | Source-line splitting and function-discovery helpers |
+| `python_style_import_bootstrap.py` | sys.path bootstrap-guard recognizer |
+| `react_checks.py` | React class-component and error-boundary checks |
+| `ruff_integration.py` | Ruff lint integration |
+| `run_all_validators.py` | Pre-push validator orchestration and report |
+| `security_checks.py` | Hardcoded-secret, SQL injection, and XSS checks |
+| `system_temporary_roots.py` | System temp-root membership for staged copies |
+| `todo_checks.py` | TODO/FIXME tracking with issue-reference requirement |
+| `type_safety_checks.py` | Missing type hints and Any usage checks |
+| `useless_test_checks.py` | Useless-test detection |
+| `validator_base.py` | Shared validator dataclasses, source read, and parse |
+| `validator_defaults.py` | Shared constants for the validators package |
 
 ## Checks Implemented
 

package/hooks/validators/fast_save_validators.py

@@ -14,7 +14,7 @@ the CLI mode calls. A save-path finding matches the CLI mode's finding for
 the same validator; only Mypy and the process-per-check overhead are gone.
 """
 
-from collections.abc import Callable, Sequence
+from collections.abc import Callable, Collection, Sequence
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -125,92 +125,61 @@ class _FastSaveValidatorSpecification:
     no_matching_files_message: str
 
 
-def _all_fast_save_validator_specifications() -> (
-    "tuple[_FastSaveValidatorSpecification, ...]"
-):
-    """Return the save-path roster: every non-Mypy, non-Ruff file-scoped check."""
+def _build_specification(
+    display_name: str,
+    checks: str,
+    applies_to_file: FilePredicate,
+    collect_violation_lines: FileViolationLineCollector,
+    no_matching_files_message: str,
+) -> _FastSaveValidatorSpecification:
+    return _FastSaveValidatorSpecification(
+        display_name,
+        checks,
+        applies_to_file,
+        collect_violation_lines,
+        no_matching_files_message,
+    )
+
+
+def _python_specifications() -> tuple[_FastSaveValidatorSpecification, ...]:
+    return (
+        _build_specification("Python Style", "1,2,3,4", _is_python_file, _violation_lines_from(validate_python_style_file), NO_PYTHON_FILES_MESSAGE),
+        _build_specification("Abbreviations", "5", _is_python_file, _violation_lines_from(validate_abbreviation_file), NO_PYTHON_FILES_MESSAGE),
+        _build_specification("Magic Values", "7", _is_python_file, _violation_lines_from(validate_magic_literal_file), NO_PYTHON_FILES_MESSAGE),
+        _build_specification("Security", "27,28,29", _is_python_file, _violation_lines_from(validate_security_file), NO_PYTHON_FILES_MESSAGE),
+        _build_specification("Code Quality", "30,31,32", _is_python_file, _violation_lines_from(validate_code_quality_file), NO_PYTHON_FILES_MESSAGE),
+        _build_specification("Python Anti-patterns", "33,34,35", _is_python_file, _violation_lines_from(validate_python_antipattern_file), NO_PYTHON_FILES_MESSAGE),
+        _build_specification("Type Safety", "39,40", _is_python_file, _violation_lines_from(validate_type_safety_file), NO_PYTHON_FILES_MESSAGE),
+    )
+
+
+def _test_specifications() -> tuple[_FastSaveValidatorSpecification, ...]:
+    return (
+        _build_specification("Test Safety", "11,21", _is_test_python_file, _collect_test_safety_violation_lines, NO_TEST_FILES_MESSAGE),
+        _build_specification("Useless Tests", "12", _is_test_python_file, _violation_lines_from(validate_useless_test_file), NO_TEST_FILES_MESSAGE),
+    )
+
+
+def _non_python_specifications() -> tuple[_FastSaveValidatorSpecification, ...]:
     return (
-        # Python naming, style, and constants.
-        _FastSaveValidatorSpecification(
-            "Python Style",
-            "1,2,3,4",
-            _is_python_file,
-            _violation_lines_from(validate_python_style_file),
-            NO_PYTHON_FILES_MESSAGE,
-        ),
-        _FastSaveValidatorSpecification(
-            "Abbreviations",
-            "5",
-            _is_python_file,
-            _violation_lines_from(validate_abbreviation_file),
-            NO_PYTHON_FILES_MESSAGE,
-        ),
-        _FastSaveValidatorSpecification(
-            "Magic Values",
-            "7",
-            _is_python_file,
-            _violation_lines_from(validate_magic_literal_file),
-            NO_PYTHON_FILES_MESSAGE,
-        ),
-        _FastSaveValidatorSpecification(
-            "Security",
-            "27,28,29",
-            _is_python_file,
-            _violation_lines_from(validate_security_file),
-            NO_PYTHON_FILES_MESSAGE,
-        ),
-        _FastSaveValidatorSpecification(
-            "Code Quality",
-            "30,31,32",
-            _is_python_file,
-            _violation_lines_from(validate_code_quality_file),
-            NO_PYTHON_FILES_MESSAGE,
-        ),
-        # Python anti-patterns and typing.
-        _FastSaveValidatorSpecification(
-            "Python Anti-patterns",
-            "33,34,35",
-            _is_python_file,
-            _violation_lines_from(validate_python_antipattern_file),
-            NO_PYTHON_FILES_MESSAGE,
-        ),
-        _FastSaveValidatorSpecification(
-            "Type Safety",
-            "39,40",
-            _is_python_file,
-            _violation_lines_from(validate_type_safety_file),
-            NO_PYTHON_FILES_MESSAGE,
-        ),
-        # Scoped to a test_*.py-shaped file.
-        _FastSaveValidatorSpecification(
-            "Test Safety",
-            "11,21",
-            _is_test_python_file,
-            _collect_test_safety_violation_lines,
-            NO_TEST_FILES_MESSAGE,
-        ),
-        _FastSaveValidatorSpecification(
-            "Useless Tests",
-            "12",
-            _is_test_python_file,
-            _violation_lines_from(validate_useless_test_file),
-            NO_TEST_FILES_MESSAGE,
-        ),
-        # Non-Python or multi-language files.
-        _FastSaveValidatorSpecification(
-            "React",
-            "17",
-            _is_react_file,
-            _collect_react_violation_lines,
-            NO_REACT_FILES_MESSAGE,
-        ),
-        _FastSaveValidatorSpecification(
-            "PR References",
-            "6",
-            _is_code_reference_file,
-            _violation_lines_from(validate_pr_reference_file),
-            NO_CODE_REFERENCE_FILES_MESSAGE,
-        ),
+        _build_specification("React", "17", _is_react_file, _collect_react_violation_lines, NO_REACT_FILES_MESSAGE),
+        _build_specification("PR References", "6", _is_code_reference_file, _violation_lines_from(validate_pr_reference_file), NO_CODE_REFERENCE_FILES_MESSAGE),
+    )
+
+
+def _all_fast_save_validator_specifications(
+    excluded_validator_names: Collection[str] = (),
+) -> tuple[_FastSaveValidatorSpecification, ...]:
+    """Return the save-path roster: every non-Mypy, non-Ruff file-scoped check."""
+    all_specifications = (
+        *_python_specifications(),
+        *_test_specifications(),
+        *_non_python_specifications(),
+    )
+    return tuple(
+        each_specification
+        for each_specification in all_specifications
+        if each_specification.display_name not in excluded_validator_names
     )
 
 
@@ -250,11 +219,14 @@ def _run_specification(
     return _fast_save_outcome(specification, False, violation_report)
 
 
-def run_fast_save_validators(files: "list[Path]") -> "list[ValidatorResult]":
+def run_fast_save_validators(
+    files: "list[Path]", excluded_validator_names: Collection[str] = ()
+) -> "list[ValidatorResult]":
     """Run every save-path validator in-process, skipping Mypy and Ruff.
 
     Args:
-        files: The files under validation -- one reconstructed file in gate mode.
+        files: Files under validation. Gate mode passes one reconstructed file.
+        excluded_validator_names: Display names omitted from this run.
 
     Returns:
         One result per in-process validator, in roster order. The caller adds
@@ -262,5 +234,7 @@ def run_fast_save_validators(files: "list[Path]") -> "list[ValidatorResult]":
     """
     return [
         _run_specification(each_specification, files)
-        for each_specification in _all_fast_save_validator_specifications()
+        for each_specification in _all_fast_save_validator_specifications(
+            excluded_validator_names
+        )
     ]