claude-dev-env 1.89.0 → 1.92.0

package/CLAUDE.md

@@ -4,19 +4,6 @@ The user is short on time and appreciates brevity in replies. When you reply, al
 
 The user delegates execution to you and expects zero manual steps unless strictly necessary. Execute every command you can directly. Only instruct the user to do something manually when you are technically unable to do it yourself. When a task involves credentials or other sensitive input, display a minimal secure UI (e.g., a password dialog) to collect it rather than asking the user to paste it into chat or run the command themselves. When direction is ambiguous, use AskUserQuestion to clarify before acting.
 
-You have access to an `advisor` tool backed by a stronger reviewer model. It takes NO parameters — when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen.
-
-Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.
-
-Also call advisor:
-- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
-- When stuck — errors recurring, approach not converging, results that don't fit.
-- When considering a change of approach.
-
-On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling — the advisor adds most of its value on the first call, before the approach crystallizes.
-
-ALWAYS call the AskUserQuestion tool if you have a question for the user. Provide content-appropriate default options, with a flag for the recommended one.
-
 ## Timeless Documentation (all `.md` files)
 
 Every Markdown file I write or edit describes the system's **current** state only. The test: a reader a year out, with zero prior context, finds every sentence true and complete without knowing what came before. State what **is**, not what changed — git history records change; docs record the contract.

package/_shared/pr-loop/scripts/code_rules_gate.py

@@ -15,6 +15,7 @@ from pr_loop_shared_constants.code_rules_gate_constants import (  # noqa: E402
     ALL_CODE_FILE_EXTENSIONS,
     ALL_GIT_DIFF_CACHED_NAME_ONLY_NULL_TERMINATED_COMMAND,
     ALL_GIT_DIFF_NAME_ONLY_NULL_TERMINATED_COMMAND_PREFIX,
+    ALL_PYTEST_CONFIG_FILE_SECTIONS,
     ALL_PYTEST_MODULE_INVOCATION,
     ALL_TEST_FILENAME_GLOB_SUFFIXES,
     ALL_TEST_FILENAME_SUFFIXES,
@@ -38,6 +39,7 @@ from pr_loop_shared_constants.code_rules_gate_constants import (  # noqa: E402
     PYTHON_FILE_EXTENSION,
     STAGED_PYTEST_TIMEOUT_SECONDS,
     STAGED_TEST_FAILURE_HEADER,
+    STAGED_TEST_GROUP_FAILURE_MESSAGE,
     TEST_CONFTEST_FILENAME,
     TEST_FILENAME_PREFIX,
     TESTS_PATH_SEGMENT,
@@ -1559,39 +1561,129 @@ def _staged_test_file_paths(repository_root: Path) -> list[Path]:
     return all_test_paths
 
 
-def run_staged_test_files(repository_root: Path) -> int:
-    """Run pytest over the staged test files and return the gate exit code.
+def _directory_holds_pytest_config(directory: Path) -> bool:
+    """Return True when *directory* holds a recognized pytest configuration file."""
+    for each_filename, each_required_section in ALL_PYTEST_CONFIG_FILE_SECTIONS:
+        config_path = directory / each_filename
+        if not config_path.is_file():
+            continue
+        if each_required_section is None:
+            return True
+        try:
+            config_text = config_path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        if each_required_section in config_text:
+            return True
+    return False
+
+
+def _resolve_owning_test_root(test_file_path: Path, repository_root: Path) -> Path:
+    """Return the nearest ancestor of *test_file_path* that owns a pytest config.
+
+    Walks up from the test file to the first directory holding a pytest config,
+    stopping at *repository_root*, which is the fallback when none is found.
 
     Args:
-        repository_root: The repository root the staged test files belong to.
+        test_file_path: The staged test file to resolve a root for.
+        repository_root: The repository root that bounds the upward walk.
 
     Returns:
-        0 when no test file is staged, when the staged test files collect
-        no tests (pytest's no-tests-collected exit code), or when every staged
-        test passes. pytest's non-zero exit code otherwise, which blocks the
-        commit.
+        The resolved owning test root directory.
+    """
+    resolved_repository_root = repository_root.resolve()
+    for each_ancestor in test_file_path.resolve().parents:
+        if _directory_holds_pytest_config(each_ancestor):
+            return each_ancestor
+        if each_ancestor == resolved_repository_root:
+            return resolved_repository_root
+    return resolved_repository_root
+
+
+def _group_staged_tests_by_root(
+    all_test_paths: list[Path],
+    repository_root: Path,
+) -> dict[Path, list[Path]]:
+    """Group *all_test_paths* by their owning pytest-config root.
+
+    Args:
+        all_test_paths: The staged test files to partition.
+        repository_root: The repository root that bounds each upward walk.
+
+    Returns:
+        A mapping from owning test root to the staged test files under it.
+    """
+    tests_by_root: dict[Path, list[Path]] = {}
+    for each_test_path in all_test_paths:
+        owning_root = _resolve_owning_test_root(each_test_path, repository_root)
+        tests_by_root.setdefault(owning_root, []).append(each_test_path)
+    return tests_by_root
+
+
+def _run_pytest_for_group(group_root: Path, all_group_test_paths: list[Path]) -> int:
+    """Run pytest over one group's test files with the working directory at its root.
+
+    Args:
+        group_root: The owning test root used as the pytest working directory.
+        all_group_test_paths: The staged test files that share *group_root*.
+
+    Returns:
+        0 when the group's tests pass or collect nothing; pytest's non-zero
+        exit code otherwise.
     """
-    all_test_paths = _staged_test_file_paths(repository_root)
-    if not all_test_paths:
-        return 0
     pytest_process = subprocess.run(
         [
             sys.executable,
             *ALL_PYTEST_MODULE_INVOCATION,
-            *[str(each_path) for each_path in all_test_paths],
+            *[str(each_path) for each_path in all_group_test_paths],
         ],
-        cwd=str(repository_root),
+        cwd=str(group_root),
         timeout=STAGED_PYTEST_TIMEOUT_SECONDS,
         check=False,
         env=repository_environment(),
     )
     if pytest_process.returncode == PYTEST_NO_TESTS_COLLECTED_EXIT_CODE:
         return 0
-    if pytest_process.returncode != 0:
-        print(STAGED_TEST_FAILURE_HEADER, file=sys.stderr)
     return pytest_process.returncode
 
 
+def run_staged_test_files(repository_root: Path) -> int:
+    """Run pytest over the staged test files and return the gate exit code.
+
+    Groups the staged test files by their owning pytest-config root and runs one
+    pytest session per group with the working directory at that root, so two
+    packages that expose a same-named top-level package never share one session
+    and shadow each other's imports.
+
+    Args:
+        repository_root: The repository root the staged test files belong to.
+
+    Returns:
+        0 when no test file is staged, when every group collects no tests, or
+        when every group passes. The first failing group's non-zero pytest exit
+        code otherwise, which blocks the commit.
+    """
+    all_test_paths = _staged_test_file_paths(repository_root)
+    if not all_test_paths:
+        return 0
+    tests_by_root = _group_staged_tests_by_root(all_test_paths, repository_root)
+    first_failing_exit_code = 0
+    for each_group_root in sorted(tests_by_root):
+        group_exit_code = _run_pytest_for_group(
+            each_group_root, tests_by_root[each_group_root]
+        )
+        if group_exit_code != 0:
+            print(
+                STAGED_TEST_GROUP_FAILURE_MESSAGE.format(group_root=each_group_root),
+                file=sys.stderr,
+            )
+            if first_failing_exit_code == 0:
+                first_failing_exit_code = group_exit_code
+    if first_failing_exit_code != 0:
+        print(STAGED_TEST_FAILURE_HEADER, file=sys.stderr)
+    return first_failing_exit_code
+
+
 def _report_terminology_findings(all_findings: list[str]) -> None:
     """Print the terminology-sweep findings, when any, to standard error.
 

package/_shared/pr-loop/scripts/pr_loop_shared_constants/code_rules_gate_constants.py

@@ -93,3 +93,29 @@ STAGED_PYTEST_TIMEOUT_SECONDS: int = 600
 STAGED_TEST_FAILURE_HEADER: str = (
     "code_rules_gate: staged test file(s) failed under pytest; commit blocked."
 )
+
+PYTEST_INI_FILENAME: str = "pytest.ini"
+
+PYPROJECT_TOML_FILENAME: str = "pyproject.toml"
+
+SETUP_CFG_FILENAME: str = "setup.cfg"
+
+TOX_INI_FILENAME: str = "tox.ini"
+
+PYPROJECT_PYTEST_CONFIG_SECTION: str = "[tool.pytest.ini_options]"
+
+SETUP_CFG_PYTEST_CONFIG_SECTION: str = "[tool:pytest]"
+
+TOX_INI_PYTEST_CONFIG_SECTION: str = "[pytest]"
+
+ALL_PYTEST_CONFIG_FILE_SECTIONS: tuple[tuple[str, str | None], ...] = (
+    (PYTEST_INI_FILENAME, None),
+    (PYPROJECT_TOML_FILENAME, PYPROJECT_PYTEST_CONFIG_SECTION),
+    (SETUP_CFG_FILENAME, SETUP_CFG_PYTEST_CONFIG_SECTION),
+    (TOX_INI_FILENAME, TOX_INI_PYTEST_CONFIG_SECTION),
+)
+
+STAGED_TEST_GROUP_FAILURE_MESSAGE: str = (
+    "code_rules_gate: staged test group rooted at {group_root} "
+    "failed under pytest; commit blocked."
+)

package/_shared/pr-loop/scripts/tests/test_code_rules_gate.py

@@ -2418,3 +2418,163 @@ def test_run_staged_test_files_runs_pytest_without_git_environment(
     monkeypatch.setenv("GIT_AUTHOR_NAME", "Hostile Hook Environment")
 
     assert gate_module.run_staged_test_files(repository_root) == 0
+
+
+def _build_shadowing_skill(
+    repository_root: Path,
+    skill_name: str,
+    module_name: str,
+) -> Path:
+    skill_directory = repository_root / skill_name
+    write_file(skill_directory / "pytest.ini", "[pytest]\n")
+    write_file(skill_directory / "scripts" / "__init__.py", "")
+    write_file(
+        skill_directory / "scripts" / f"{module_name}.py",
+        f"{module_name}_marker = 1\n",
+    )
+    test_relative_path = f"{skill_name}/test_{module_name}.py"
+    write_file(
+        repository_root / test_relative_path,
+        f"from scripts.{module_name} import {module_name}_marker\n"
+        "\n"
+        "\n"
+        f"def test_{module_name}_marker_is_one() -> None:\n"
+        f"    assert {module_name}_marker == 1\n",
+    )
+    stage_file(repository_root, test_relative_path)
+    return repository_root / test_relative_path
+
+
+def test_run_staged_test_files_passes_when_same_named_package_would_shadow(
+    temporary_git_repository: Path,
+) -> None:
+    """Two skill roots each own a top-level ``scripts`` package. One combined
+    pytest session binds ``scripts`` to whichever imports first and the other
+    skill's ``from scripts.<module>`` then raises ImportError. Per-root sessions
+    keep each ``scripts`` isolated, so the gate passes."""
+    first_test_path = _build_shadowing_skill(
+        temporary_git_repository, "skill_alpha", "widget"
+    )
+    second_test_path = _build_shadowing_skill(
+        temporary_git_repository, "skill_beta", "gadget"
+    )
+
+    combined_session = subprocess.run(
+        [sys.executable, "-m", "pytest", "-q", str(first_test_path), str(second_test_path)],
+        cwd=str(temporary_git_repository),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+    )
+    assert combined_session.returncode != 0, (
+        "one combined pytest session must fail on the same-named scripts package "
+        "shadow; if it does not, the shadow scenario is not being reproduced"
+    )
+
+    assert gate_module.run_staged_test_files(temporary_git_repository) == 0, (
+        "per-root pytest sessions must keep each scripts package isolated so both "
+        "staged suites pass"
+    )
+
+
+def test_resolve_owning_test_root_returns_pyproject_config_directory(
+    tmp_path: Path,
+) -> None:
+    package_root = tmp_path / "package_root"
+    write_file(
+        package_root / "pyproject.toml",
+        "[tool.pytest.ini_options]\ntestpaths = ['tests']\n",
+    )
+    test_path = package_root / "tests" / "test_behavior.py"
+    write_file(test_path, "def test_behavior() -> None:\n    assert True\n")
+
+    resolved_root = gate_module._resolve_owning_test_root(test_path, tmp_path)
+
+    assert resolved_root == package_root.resolve()
+
+
+def test_resolve_owning_test_root_returns_pytest_ini_directory(
+    tmp_path: Path,
+) -> None:
+    package_root = tmp_path / "package_root"
+    write_file(package_root / "pytest.ini", "[pytest]\n")
+    test_path = package_root / "suite" / "test_behavior.py"
+    write_file(test_path, "def test_behavior() -> None:\n    assert True\n")
+
+    resolved_root = gate_module._resolve_owning_test_root(test_path, tmp_path)
+
+    assert resolved_root == package_root.resolve()
+
+
+def test_resolve_owning_test_root_falls_back_to_repository_root(
+    tmp_path: Path,
+) -> None:
+    test_path = tmp_path / "nested" / "deeper" / "test_behavior.py"
+    write_file(test_path, "def test_behavior() -> None:\n    assert True\n")
+
+    resolved_root = gate_module._resolve_owning_test_root(test_path, tmp_path)
+
+    assert resolved_root == tmp_path.resolve()
+
+
+def test_resolve_owning_test_root_skips_pyproject_without_pytest_section(
+    tmp_path: Path,
+) -> None:
+    outer_root = tmp_path / "outer"
+    write_file(
+        outer_root / "pyproject.toml",
+        "[tool.pytest.ini_options]\ntestpaths = ['tests']\n",
+    )
+    write_file(outer_root / "inner" / "pyproject.toml", "[project]\nname = 'inner'\n")
+    test_path = outer_root / "inner" / "test_behavior.py"
+    write_file(test_path, "def test_behavior() -> None:\n    assert True\n")
+
+    resolved_root = gate_module._resolve_owning_test_root(test_path, tmp_path)
+
+    assert resolved_root == outer_root.resolve()
+
+
+def test_group_staged_tests_by_root_shares_a_session_for_same_root(
+    tmp_path: Path,
+) -> None:
+    package_root = tmp_path / "package_root"
+    write_file(package_root / "pytest.ini", "[pytest]\n")
+    first_test_path = package_root / "tests" / "test_first.py"
+    second_test_path = package_root / "tests" / "test_second.py"
+    write_file(first_test_path, "def test_first() -> None:\n    assert True\n")
+    write_file(second_test_path, "def test_second() -> None:\n    assert True\n")
+
+    tests_by_root = gate_module._group_staged_tests_by_root(
+        [first_test_path, second_test_path], tmp_path
+    )
+
+    assert set(tests_by_root) == {package_root.resolve()}
+    assert sorted(tests_by_root[package_root.resolve()]) == sorted(
+        [first_test_path, second_test_path]
+    )
+
+
+def test_run_staged_test_files_fails_when_one_group_fails(
+    temporary_git_repository: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    write_file(temporary_git_repository / "passing_skill" / "pytest.ini", "[pytest]\n")
+    write_file(
+        temporary_git_repository / "passing_skill" / "test_pass.py",
+        "def test_pass() -> None:\n    assert True\n",
+    )
+    stage_file(temporary_git_repository, "passing_skill/test_pass.py")
+    write_file(temporary_git_repository / "failing_skill" / "pytest.ini", "[pytest]\n")
+    write_file(
+        temporary_git_repository / "failing_skill" / "test_fail.py",
+        "def test_fail() -> None:\n    assert False\n",
+    )
+    stage_file(temporary_git_repository, "failing_skill/test_fail.py")
+
+    exit_code = gate_module.run_staged_test_files(temporary_git_repository)
+
+    assert exit_code != 0
+    captured_error = capsys.readouterr().err
+    assert "failing_skill" in captured_error

package/agents/clean-coder.md

@@ -159,7 +159,7 @@ Use logging for application and runtime output. `print()` is allowed when stdout
 
 ### Comment preservation
 
-Existing comments on lines that remain otherwise unchanged stay exactly as you found them. The hook enforces both directions: the gate fires on a new inline `#` or `//` in production code, and the gate also fires when an existing comment disappears from a line you touched. New code self-documents via names; new docstrings on functions, methods, classes, and modules remain allowed.
+Existing comments on lines you leave otherwise unchanged stay exactly as you found them. The hook treats the two directions differently: the gate fires and blocks the edit on a new inline `#` or `//` in production code, while an existing comment disappearing from a line you touched prints a stderr advisory and lets the edit through. New code self-documents via names; new docstrings on functions, methods, classes, and modules stay allowed.
 
 ### Centralized configuration
 
@@ -338,7 +338,7 @@ These gates are checked by `code_rules_enforcer.py`. Satisfying each gate lets y
 | Rule | What this rule looks for |
 |------|--------------------------|
 | Self-documenting names only | New `#` or `//` in production code (shebangs, `# type:`, `# noqa`, eslint-directives, docstrings exempt) |
-| Comment preservation | Removal of existing comments on lines that remain otherwise unchanged |
+| Comment preservation | Advisory — removal of existing comments on lines you leave otherwise unchanged prints a stderr advisory and does not block |
 | Imports at top | `import` statements placed inside function bodies |
 | Logging format | `log_*(f"...")` — replace with `log_*("...", arg)` |
 | File length | Advisory at 400 lines (soft), strong nudge at 1000 — emitted to stderr; the write proceeds |

package/agents/code-verifier.md

@@ -3,7 +3,6 @@ name: code-verifier
 description: Post-hoc verification agent for the two-phase code workflow. Spawned by the main session after coder agents finish. Runs every check itself in a fresh context — named gates, tests against recorded baselines, two-way diff-vs-task reading — and ends with a fenced verdict block the verifier_verdict_minter hook turns into the commit-gate verdict. Read and execute only; it never edits files.
 tools: Read, Grep, Glob, Bash
 model: sonnet
-effort: medium
 color: orange
 ---
 

package/agents/test_agent_frontmatter.py

@@ -0,0 +1,78 @@
+"""Behavior tests for agent-definition YAML frontmatter.
+
+Every agent `.md` in this directory opens with a frontmatter block the Claude
+Code subagent loader reads. The loader accepts a fixed key set; an unrecognized
+top-level key breaks the spawn — the subagent starts with a broken definition,
+idles, and dies without a report::
+
+    ok:   name / description / tools / model / color
+    flag: effort            <- unrecognized, subagent dies delivering nothing
+
+The accepted set is the one `agents/CLAUDE.md` documents (name, description,
+tools, color) plus the `model` pin the working agents carry (clean-coder pins
+opus, pr-description-writer pins haiku). Top-level keys are read with a line
+scan so an agent whose `description` embeds informal `<example>` prose is not
+mistaken for one carrying extra keys.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+import yaml
+
+ACCEPTED_FRONTMATTER_KEYS = frozenset(
+    {"name", "description", "tools", "model", "color"}
+)
+FRONTMATTER_FENCE = "---"
+FRONTMATTER_SEGMENT_COUNT = 3
+CODE_VERIFIER_AGENT_NAME = "code-verifier"
+TOP_LEVEL_KEY_PATTERN = re.compile(r"^([a-z][a-z0-9_]*):", re.MULTILINE)
+
+
+def _agent_definition_paths() -> list[Path]:
+    agents_directory = Path(__file__).parent
+    all_markdown_files = sorted(agents_directory.glob("*.md"))
+    return [
+        each_markdown_file
+        for each_markdown_file in all_markdown_files
+        if each_markdown_file.read_text(encoding="utf-8").startswith(FRONTMATTER_FENCE)
+    ]
+
+
+def _frontmatter_block(agent_definition_path: Path) -> str:
+    agent_text = agent_definition_path.read_text(encoding="utf-8")
+    fence_segments = agent_text.split(FRONTMATTER_FENCE, FRONTMATTER_SEGMENT_COUNT - 1)
+    return fence_segments[1]
+
+
+def _top_level_keys(frontmatter_block: str) -> set[str]:
+    return set(TOP_LEVEL_KEY_PATTERN.findall(frontmatter_block))
+
+
+@pytest.mark.parametrize(
+    "agent_definition_path",
+    _agent_definition_paths(),
+    ids=lambda each_path: each_path.name,
+)
+def test_agent_frontmatter_uses_only_accepted_keys(
+    agent_definition_path: Path,
+) -> None:
+    declared_keys = _top_level_keys(_frontmatter_block(agent_definition_path))
+    unaccepted_keys = declared_keys - ACCEPTED_FRONTMATTER_KEYS
+    assert not unaccepted_keys, (
+        f"{agent_definition_path.name} carries frontmatter keys the subagent "
+        f"loader does not accept: {sorted(unaccepted_keys)}"
+    )
+
+
+def test_code_verifier_frontmatter_parses_and_names_the_agent() -> None:
+    agents_directory = Path(__file__).parent
+    code_verifier_block = _frontmatter_block(
+        agents_directory / f"{CODE_VERIFIER_AGENT_NAME}.md"
+    )
+    parsed_frontmatter = yaml.safe_load(code_verifier_block)
+    assert parsed_frontmatter["name"] == CODE_VERIFIER_AGENT_NAME
+    assert set(parsed_frontmatter) <= ACCEPTED_FRONTMATTER_KEYS

package/audit-rubrics/category_rubrics/category-j-code-rules-compliance.md

@@ -24,7 +24,7 @@
 | J5 | Abbreviations | `ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `elem`, `val`, `tmp`, `str`, `num`, `arr`, `obj`, `fn`, `cb`, `req`, `res`. (Loop counters `i`/`j`/`k` and `e` for exceptions are exempt.) |
 | J6 | Vague names | `result`, `data`, `output`, `response`, `value`, `item`, `temp`, `info`, `stuff`, `thing`. Vague prefixes: `handle`, `process`, `manage`, `do`. |
 | J7 | Type hints | Missing type annotation on a parameter or return; presence of `Any` or `# type: ignore`. |
-| J8 | New inline comments | New `#` or `//` comments in production code added by this diff. (Existing comments are NEVER removed — Comment Preservation rule.) |
+| J8 | New inline comments | New `#` or `//` comments in production code added by this diff. (Removing an existing comment is a Comment Preservation concern the hook flags with a stderr advisory rather than a block.) |
 | J9 | Logging format | `log_*(f"...")` rather than `log_*("...", arg)`. |
 | J10 | Imports inside functions | `import` statements placed inside function bodies. |
 | J11 | sys.path.insert dedup | `sys.path.insert(0, X)` must be guarded by `if X not in sys.path:` (test files exempt). |

package/audit-rubrics/prompts/category-j-code-rules-compliance.md

@@ -69,7 +69,7 @@ A `test_*.py` name or a `.mjs` extension takes the line out of the write-time ga
 **J8. New inline comments**
 - Every `#` or `//` comment line **added** by this diff in production code — flag, except for exempt markers (shebangs, `# type:`, `# noqa`, `# pylint:`, `# pragma:`, `// @ts-`, `// eslint-`, `// prettier-`, `/// `).
 - Module/function/class docstrings are always allowed.
-- Existing comments are NEVER removed (Comment Preservation rule); if the diff removes an existing comment, that is a separate violation outside J8 (also blocked by the hook).
+- Existing comments are NEVER removed (Comment Preservation rule); if the diff removes an existing comment, that is a separate violation outside J8 (the hook emits a stderr advisory for it rather than blocking).
 - Test files are exempt.
 - Adversarial probes: (a) is there any `# type:` or marker comment that is actually inert prose rather than a real type-checker / linter directive? (b) is any docstring carrying inline-comment content (line-level explanations rather than module/function description)? (c) does any newly-added blank line between code stanzas function as a comment substitute, suggesting the author wanted to add a comment but couldn't?
 

package/bin/install.mjs

@@ -147,6 +147,7 @@ const INSTALL_GROUPS = {
     core: {
         description: 'Development standards, hooks, agents, commands',
         skills: [
+            'team-advisor', 'team-advisor-refresh',
             'anthropic-plan', 'everything-search',
             'pr-review-responder',
             'recall', 'remember', 'task-build', 'verified-build'

package/docs/CODE_RULES.md

@@ -4,9 +4,9 @@ Compact reference for agents. ⚡ marks rules enforced by `code_rules_enforcer.p
 
 ---
 
-## COMMENT PRESERVATION (ABSOLUTE RULE)
+## COMMENT PRESERVATION
 
-**NEVER remove existing comments.** Existing comments are SACRED. Only evaluate comments on lines you are actively changing. Do not add new inline comments in production code — write self-documenting code. Docstrings (module/class/function) are always allowed. Test files are exempt. The hook enforces both directions: it blocks new inline comments AND blocks deletion of existing ones.
+**Keep existing comments in place.** Only evaluate comments on lines you are actively changing. Do not add new inline comments in production code — write self-documenting code. Docstrings (module/class/function) are always allowed. Test files are exempt. The hook treats the two directions differently: adding a new inline comment blocks the edit, while removing an existing comment prints a stderr advisory and lets the edit through.
 
 ---
 

package/hooks/blocking/CLAUDE.md

@@ -24,7 +24,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `code_rules_banned_identifiers.py` | Banned short names (`ctx`, `cfg`, `msg`, etc.), banned prefixes (`handle_`, `process_`, etc.) |
 | `code_rules_boolean_mustcheck.py` | Boolean naming (`is_`/`has_`/… prefixes) and must-check return values |
 | `code_rules_command_dispatch.py` | A `hooks/blocking/` command classifier matching a multi-word command regex without a start anchor or first-word tokenization |
-| `code_rules_comments.py` | No new inline comments; no deletion of existing ones |
+| `code_rules_comments.py` | No new inline comments; advisory on deletion of existing ones |
 | `code_rules_constants_config.py` | Constants must live in `config/`; file-global constant use-count |
 | `code_rules_dead_argparse_argument.py` | Argparse arguments with no references in the same file |
 | `code_rules_dead_config_field.py` | `*Config` / `*Selectors` dataclass fields with no live references |
@@ -78,10 +78,11 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `hook_prose_detector_consistency.py` | PreToolUse (Write/Edit) | Hook docstrings/messages that claim a trigger the detector cannot fire on |
 | `intent_only_ending_blocker.py` | Stop | Responses that end on a plan or intent without doing the work |
 | `open_questions_in_plans_blocker.py` | PreToolUse (Write/Edit) | Plan documents with unresolved open questions |
+| `nas_ssh_binary_enforcer.py` | PreToolUse (Bash) | A bare `ssh`/`scp`/`sftp` command word targeting the NAS at `192.168.1.100` (Git Bash's MSYS ssh stalls on an interactive password prompt), or the full `System32/OpenSSH` binary to that host without `-o BatchMode=yes` |
 | `package_inventory_stale_blocker.py` | PreToolUse (Write) | A new production code file created in a directory whose `README.md`/`CLAUDE.md` inventory (or a parent skill's `SKILL.md` Layout table mapping the `scripts/` subdirectory) names two or more sibling files but no entry for the new file |
 | `plain_language_blocker.py` | PreToolUse (Write/Edit/AskUserQuestion) | Heavy or jargon words in user-facing prose |
 | `pr_converge_bugteam_enforcer.py` | PreToolUse | Enforces that bugteam runs in parallel with bugbot in pr-converge loops |
-| `pr_description_enforcer.py` | PreToolUse (Bash) | `gh pr create`/`edit`/`comment` bodies that fail the Anthropic claude-code style audit |
+| `pr_description_enforcer.py` | PreToolUse (Bash) | `gh pr create`/`edit`/`comment` bodies that fail the Anthropic claude-code style audit, proof-shaped `gh pr comment` bodies missing proof-of-work parts, and `gh pr ready` while the PR carries no passing proof comment |
 | `precommit_code_rules_gate.py` | PreToolUse (Bash) | Staged changes that fail the CODE_RULES gate at commit time |
 | `pytest_testpaths_orphan_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | New `test_*.py` files created under a directory absent from a package's explicit pytest `testpaths` allowlist |
 | `question_to_user_enforcer.py` | Stop | User-directed questions not routed through `AskUserQuestion` |
@@ -98,6 +99,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `verified_commit_gate.py` | PreToolUse (Bash/PowerShell) | `git commit`/`git push` without a passing verifier verdict |
 | `verified_commit_message_accuracy_blocker.py` | PreToolUse | Commit messages that misstate what the diff has |
 | `verifier_verdict_minter.py` | SubagentStop | Mints a passing verdict file when a `code-verifier` agent finishes cleanly |
+| `volatile_path_in_post_blocker.py` | PreToolUse (Bash/MCP GitHub) | `gh` post commands and GitHub MCP post tools whose body references a volatile path (job scratch dir, worktree, or system temp) that outlives the durable post |
 | `windows_rmtree_blocker.py` | PreToolUse (Write/Edit) | `shutil.rmtree` with `ignore_errors=True` on Windows |
 | `workflow_substitution_slot_blocker.py` | PreToolUse (Write/Edit) | Workflow templates with bare per-iteration tokens missing angle-bracket slots |
 | `write_existing_file_blocker.py` | PreToolUse (Write) | Write to a path where a file already exists |
@@ -110,8 +112,10 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `pr_description_body_audit.py` | Body audit logic for `pr_description_enforcer.py` |
 | `pr_description_command_parser.py` | `gh` command parsing for `pr_description_enforcer.py` |
 | `pr_description_pr_number.py` | PR number extraction logic |
+| `pr_description_proof_of_work.py` | Proof-of-work comment audit and `gh pr ready` gate logic for `pr_description_enforcer.py` |
 | `pr_description_readability.py` | Readability checks on PR description bodies |
 | `verification_verdict_store.py` | Reads and writes verdict files under `~/.claude/verification/` |
+| `verified_commit_config_bootstrap.py` | Binds `config.verified_commit_constants` to the sibling `config/` file by explicit location, so the gate family resolves its constants regardless of a foreign `config` package's `sys.path` order |
 
 ## Conventions
 

package/hooks/blocking/code_rules_comments.py

@@ -147,7 +147,7 @@ def check_comment_changes(old_content: str, new_content: str, file_path: str) ->
 
     Inline comments (after code on same line): BLOCK when added.
     Standalone comment lines: NUDGE (print advisory) when added.
-    Existing comments being removed: BLOCK (comment preservation principle).
+    Existing comments being removed: NUDGE (print advisory) — comment preservation is advisory.
 
     When the file is Python and either *old_content* or *new_content* cannot
     be tokenized (common for mid-edit Edit fragments), the comparison is
@@ -188,7 +188,7 @@ def check_comment_changes(old_content: str, new_content: str, file_path: str) ->
         code_was_removed = new_line_count < old_line_count - len(removed_comments)
         if not code_was_removed:
             sample = next(iter(removed_comments))
-            issues.append(f"Existing comment removed: {sample[:60]} - NEVER delete existing comments")
+            print(f"[CODE_RULES advisory] Existing comment removed: {sample[:60]} - comment preservation is advisory", file=sys.stderr)
 
     return issues