claude-dev-env 8.2.0 → 8.4.0

package/rules/testing.md

@@ -26,5 +26,3 @@ Tests exercise production behavior, production data, and production code paths.
 ## No Gate Holds the Test-First Order
 
 `tdd_enforcer.py` once required a fresh, failing test before a production module was written. Nothing runs it now, and the staged policy lint carries no replacement. Hold the red-green-refactor order yourself, and let review check it on the diff.
-
-`hooks/observability/test_failure_recorder.py` still runs on every Bash call. It records a single unchained pytest run that names a test file path and reports a failing exit status, storing the command, that exit status, and the path in the content-hash store. `content_hash_store.py`'s module docstring holds the full contract. No gate reads that store today, so the record serves as history rather than a precondition.

package/scripts/dev_env_scripts_constants/grok_worker_constants.py

@@ -85,14 +85,14 @@ ROLE_BUGTEAM: str = "bugteam"
 """Role name whose agent definition set the preflight validates by default."""
 
 ROLE_CLEAN_CODER: str = "clean-coder"
-"""Role name that maps to the clean-coder agent for FIX and standards-fix."""
+"""Compatibility role for FIX and standards-fix using poteto-agent."""
 
 DEFAULT_ROLE: str = ROLE_BUGTEAM
 """Role applied when the caller does not pass ``--role``."""
 
 ALL_AGENT_FILENAMES_BY_ROLE: dict[str, tuple[str, ...]] = {
-    ROLE_BUGTEAM: ("code-quality-agent.md", "clean-coder.md"),
-    ROLE_CLEAN_CODER: ("clean-coder.md",),
+    ROLE_BUGTEAM: ("poteto-agent.md",),
+    ROLE_CLEAN_CODER: ("poteto-agent.md",),
 }
 """Agent definition filenames required under ``agents/`` for each known role."""
 

package/scripts/grok_headless_runner.py

@@ -19,7 +19,7 @@ Import ``run_headless_worker`` for the outcome object::
         working_directory=cwd,
         run_state_directory=run_dir,
         timeout_seconds=5400,
-        agent_name="code-quality-agent",
+        agent_name="poteto-agent",
     )
 """
 
@@ -72,6 +72,7 @@ from dev_env_scripts_constants.grok_worker_constants import (
     WORKER_SPEC_TIMEOUT_KEY,
 )
 from shared_tree_paths import resolve_shared_process_tree_scripts_directory
+from grok_worker_preflight import poteto_mode_skill_path
 
 _shared_process_tree_scripts_directory = resolve_shared_process_tree_scripts_directory(
     __file__,
@@ -420,6 +421,23 @@ def run_headless_worker(
         if leader_socket_path is not None
         else _mint_leader_socket_path(run_state_directory)
     )
+    if agent_name == "poteto-agent":
+        try:
+            skill_path = poteto_mode_skill_path().resolve()
+            skill_text = skill_path.read_text(encoding=UTF8_ENCODING)
+            task_text = prompt_file.read_text(encoding=UTF8_ENCODING)
+            run_state_directory.mkdir(parents=True, exist_ok=True)
+            prompt_file = run_state_directory / f"{resolved_leader_socket_path.stem}-poteto.txt"
+            prompt_file.write_text(
+                f"Poteto skill source: {skill_path}\n"
+                "Resolve companion skill paths against that source directory.\n"
+                "The task below defines your review, build, or translation duty. "
+                "Preserve its scope, write permissions, and report contract.\n\n"
+                f"{skill_text}\n\nTask:\n{task_text}",
+                encoding=UTF8_ENCODING,
+            )
+        except OSError as error:
+            return _launch_failure_outcome(error)
     all_arguments = _build_invocation(
         prompt_file=prompt_file,
         working_directory=working_directory,

package/scripts/grok_worker_preflight.py

@@ -45,6 +45,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import shutil
 import subprocess
 import sys
@@ -61,6 +62,7 @@ from dev_env_scripts_constants.grok_worker_constants import (
     CLAUDE_HOME_SUBDIRECTORY,
     CLI_PING_FLAG,
     CLI_ROLE_FLAG,
+    CLAUDE_CONFIG_DIR_ENV_VAR,
     CLI_RUN_STATE_DIR_FLAG,
     DEFAULT_AUTH_TIMEOUT_SECONDS,
     DEFAULT_PING_TIMEOUT_SECONDS,
@@ -111,7 +113,67 @@ class PreflightOutcome:
 
 def claude_config_home() -> Path:
     """Return the per-user Claude configuration directory."""
-    return Path.home() / CLAUDE_HOME_SUBDIRECTORY
+    configured_root = os.environ.get(CLAUDE_CONFIG_DIR_ENV_VAR)
+    return Path(configured_root) if configured_root else Path.home() / CLAUDE_HOME_SUBDIRECTORY
+
+
+def _read_pstack_registry(registry_path: Path) -> dict[str, object]:
+    try:
+        registry = json.loads(registry_path.read_text(encoding=UTF8_ENCODING))
+    except (UnicodeError, json.JSONDecodeError) as error:
+        raise OSError(f"Invalid pstack installation registry {registry_path}: {error}") from error
+    if not isinstance(registry, dict):
+        raise OSError(f"Invalid pstack installation registry {registry_path}: root must be an object")
+    return registry
+
+
+def _user_pstack_entries(all_registry: dict[str, object], registry_path: Path) -> list[dict[str, object]]:
+    plugins = all_registry.get("plugins")
+    if not isinstance(plugins, dict):
+        raise OSError(f"Invalid pstack installation registry {registry_path}: plugins must be an object")
+    entries = plugins.get("pstack@pstack-claude", [])
+    if not isinstance(entries, list) or any(not isinstance(entry, dict) for entry in entries):
+        raise OSError(f"Invalid pstack installation registry {registry_path}: pstack entries must be objects")
+    user_entries = [entry for entry in entries if entry.get("scope") == "user"]
+    if len(user_entries) > 1:
+        raise OSError(f"Invalid pstack installation registry {registry_path}: multiple user pstack installations")
+    return user_entries
+
+
+def _native_pstack_skill_path(registry_path: Path, fallback_path: Path) -> Path:
+    if not registry_path.exists():
+        return fallback_path
+    user_entries = _user_pstack_entries(_read_pstack_registry(registry_path), registry_path)
+    if not user_entries:
+        return fallback_path
+    install_path = user_entries[0].get("installPath")
+    if not isinstance(install_path, str) or not Path(install_path).is_absolute():
+        raise OSError(f"Invalid pstack installation registry {registry_path}: pstack installPath must be absolute")
+    return Path(install_path) / "skills" / "poteto-mode" / "SKILL.md"
+
+
+def poteto_mode_skill_path() -> Path:
+    """Return the selected installed pstack poteto-mode skill path.
+
+    Returns:
+        The validated poteto-mode skill path.
+
+    Raises:
+        OSError: If the registry or selected skill is invalid.
+    """
+    config_root = claude_config_home()
+    fallback_path = config_root / "skills" / "poteto-mode" / "SKILL.md"
+    skill_path = _native_pstack_skill_path(
+        config_root / "plugins" / "installed_plugins.json",
+        fallback_path,
+    )
+    try:
+        skill_text = skill_path.read_text(encoding=UTF8_ENCODING)
+    except UnicodeError as error:
+        raise OSError(f"Invalid UTF-8 poteto skill {skill_path}") from error
+    if not skill_text.strip():
+        raise OSError(f"Empty poteto skill {skill_path}")
+    return skill_path
 
 
 def _install_manifest_path() -> Path:
@@ -218,6 +280,10 @@ def _is_grok_binary_resolvable() -> bool:
 def _is_claude_dev_env_config_present(role: str) -> bool:
     if not _install_manifest_path().is_file():
         return False
+    try:
+        poteto_mode_skill_path()
+    except OSError:
+        return False
     all_agent_filenames = ALL_AGENT_FILENAMES_BY_ROLE.get(role)
     if all_agent_filenames is None:
         return False

package/scripts/policy_lint/config/approved_test_pairs.py

@@ -5,6 +5,15 @@ from pathlib import PurePosixPath
 APPROVED_TEST_PATHS_BY_PRODUCTION_PATH: dict[
     PurePosixPath, frozenset[PurePosixPath]
 ] = {
+    PurePosixPath(
+        ".cursor/skills/verify-claude-dev-env/scripts/verify_installer_constants/constants.mjs"
+    ): frozenset(
+        {
+            PurePosixPath(
+                ".cursor/skills/verify-claude-dev-env/scripts/verify-installer.test.mjs"
+            ),
+        }
+    ),
     PurePosixPath("packages/claude-dev-env/bin/install-constants.mjs"): frozenset(
         {
             PurePosixPath("packages/claude-dev-env/bin/install.cursor-rules.test.mjs"),

package/scripts/resolve_advisor_model_route.mjs

@@ -36,14 +36,14 @@ if (input !== undefined) {
         routingDecision = routingInputIssue
             ? blockedRoute(routingInputIssue)
             : resolveSubagentModelRoute({
-                agent_type: 'session-advisor',
+                agent_type: 'advisor',
                 ...(input.model !== undefined && input.model !== null ? { model: input.model } : {}),
                 ...(input.reasoning_effort !== undefined ? { reasoning_effort: input.reasoning_effort } : {}),
             }, {
                 policyPath: input.policyPath,
                 trustedSessionMetadata: {
                     authorized: true,
-                    registeredAgentType: 'session-advisor',
+                    registeredAgentType: 'advisor',
                 },
             });
     }

package/scripts/subagent_model_policy.mjs

@@ -298,7 +298,10 @@ function validateRoles(roles) {
         const aliases = validateStringList(roles[role], `roles.${role}`).map(normalizeToken);
         const allAliases = [role, ...aliases];
         for (const alias of allAliases) {
-            if (!isIdentifier(alias)) throw new SubagentModelPolicyError(`invalid role name: ${alias}`);
+            const roleParts = alias.split(':');
+            if (roleParts.length > 2 || !roleParts.every(isIdentifier)) {
+                throw new SubagentModelPolicyError(`invalid role name: ${alias}`);
+            }
             const previousRole = roleByAlias.get(alias);
             if (previousRole && previousRole !== role) {
                 throw new SubagentModelPolicyError(`role alias is ambiguous: ${alias}`);

package/scripts/test_grok_headless_runner.py

@@ -7,6 +7,7 @@ include the signature substrings the constants module lists.
 
 from __future__ import annotations
 
+import json
 import subprocess
 import sys
 import time
@@ -336,7 +337,11 @@ def test_argv_includes_agent_when_named(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:
     fake_process = _FakeProcess(returncode=0, stdout='{"ok":true}')
-    agent_name = "code-quality-agent"
+    agent_name = "poteto-agent"
+    skill_path = tmp_path / "poteto-mode" / "SKILL.md"
+    skill_path.parent.mkdir()
+    skill_path.write_text("Keep the requested duty.\n", encoding="utf-8")
+    monkeypatch.setattr(runner, "poteto_mode_skill_path", lambda: skill_path)
     outcome, recorder, _, _, _ = _run_once(
         monkeypatch, tmp_path, fake_process, agent_name=agent_name
     )
@@ -345,6 +350,35 @@ def test_argv_includes_agent_when_named(
     invocation = recorder.invocations[0]
     assert AGENT_FLAG in invocation
     assert agent_name in invocation
+    generated_prompt = Path(invocation[invocation.index(PROMPT_FILE_FLAG) + 1])
+    assert "Keep the requested duty." in generated_prompt.read_text(encoding="utf-8")
+    assert str(skill_path) in generated_prompt.read_text(encoding="utf-8")
+
+
+def test_native_plugin_skill_is_included_in_worker_prompt(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_root = tmp_path / "profile"
+    registry_path = config_root / "plugins" / "installed_plugins.json"
+    registry_path.parent.mkdir(parents=True)
+    plugin_root = tmp_path / "plugin" / "version"
+    registry_path.write_text(json.dumps({"plugins": {"pstack@pstack-claude": [
+        {"scope": "user", "installPath": str(plugin_root)},
+    ]}}), encoding="utf-8")
+    skill_path = plugin_root / "skills" / "poteto-mode" / "SKILL.md"
+    skill_path.parent.mkdir(parents=True)
+    skill_path.write_text("Use the native workflow.\n", encoding="utf-8")
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(config_root))
+    outcome, recorder, _, _, _ = _run_once(
+        monkeypatch, tmp_path, _FakeProcess(returncode=0, stdout="done"),
+        agent_name="poteto-agent",
+    )
+    assert outcome.is_ok
+    invocation = recorder.invocations[0]
+    prompt = Path(invocation[invocation.index(PROMPT_FILE_FLAG) + 1]).read_text(encoding="utf-8")
+    assert str(skill_path.resolve()) in prompt
+    assert "Use the native workflow." in prompt
+    assert "Resolve companion skill paths against that source directory." in prompt
 
 
 def test_unique_leader_socket_path_per_call(

package/scripts/test_grok_worker_preflight.py

@@ -80,6 +80,9 @@ class _Recorder:
 def _write_install_layout(claude_home: Path, *, role: str = ROLE_BUGTEAM) -> None:
     claude_home.mkdir(parents=True, exist_ok=True)
     (claude_home / MANIFEST_FILENAME).write_text("{}", encoding=UTF8_ENCODING)
+    skill_path = claude_home / "skills" / "poteto-mode" / "SKILL.md"
+    skill_path.parent.mkdir(parents=True, exist_ok=True)
+    skill_path.write_text("Poteto guidance\n", encoding=UTF8_ENCODING)
     agents_directory = claude_home / AGENTS_SUBDIRECTORY
     agents_directory.mkdir(parents=True, exist_ok=True)
     for each_filename in ALL_AGENT_FILENAMES_BY_ROLE[role]:
@@ -88,6 +91,76 @@ def _write_install_layout(claude_home: Path, *, role: str = ROLE_BUGTEAM) -> Non
         )
 
 
+def test_missing_poteto_skill_rejects_installed_agent(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    _write_install_layout(tmp_path)
+    monkeypatch.setattr(preflight, "claude_config_home", lambda: tmp_path)
+    assert preflight._is_claude_dev_env_config_present(ROLE_BUGTEAM)
+    preflight.poteto_mode_skill_path().unlink()
+    assert not preflight._is_claude_dev_env_config_present(ROLE_BUGTEAM)
+
+
+def _write_native_pstack(config_root: Path, plugin_root: Path) -> Path:
+    registry_path = config_root / "plugins" / "installed_plugins.json"
+    registry_path.parent.mkdir(parents=True, exist_ok=True)
+    registry_path.write_text(
+        json.dumps({"plugins": {"pstack@pstack-claude": [
+            {"scope": "user", "installPath": str(plugin_root)},
+            {"scope": "project", "installPath": str(plugin_root / "other")},
+        ]}}),
+        encoding=UTF8_ENCODING,
+    )
+    skill_path = plugin_root / "skills" / "poteto-mode" / "SKILL.md"
+    skill_path.parent.mkdir(parents=True)
+    skill_path.write_text("Native poteto guidance\n", encoding=UTF8_ENCODING)
+    companion = skill_path.parent / "playbooks" / "bug-fix.md"
+    companion.parent.mkdir()
+    companion.write_text("Fix guidance\n", encoding=UTF8_ENCODING)
+    return skill_path
+
+
+def _damage_native_plugin(config_root: Path, native_skill: Path, damage: str) -> None:
+    if damage == "missing":
+        native_skill.unlink()
+        return
+    if damage == "empty":
+        native_skill.write_text("", encoding=UTF8_ENCODING)
+        return
+    if damage == "encoding":
+        native_skill.write_bytes(b"\xff")
+        return
+    (config_root / "plugins" / "installed_plugins.json").write_text(
+        "{", encoding=UTF8_ENCODING
+    )
+
+
+def test_native_plugin_source_overrides_shared_skill(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_root = tmp_path / "profile"
+    _write_install_layout(config_root)
+    native_skill = _write_native_pstack(config_root, tmp_path / "plugin-version")
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(config_root))
+    assert preflight.poteto_mode_skill_path() == native_skill
+    assert (native_skill.parent / "playbooks" / "bug-fix.md").read_text() == "Fix guidance\n"
+    assert preflight._is_claude_dev_env_config_present(ROLE_BUGTEAM)
+
+
+@pytest.mark.parametrize("damage", ["missing", "empty", "encoding", "registry"])
+def test_broken_native_plugin_does_not_fall_back_to_shared_skill(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, damage: str
+) -> None:
+    config_root = tmp_path / "profile"
+    _write_install_layout(config_root)
+    native_skill = _write_native_pstack(config_root, tmp_path / "plugin-version")
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(config_root))
+    _damage_native_plugin(config_root, native_skill, damage)
+    with pytest.raises(OSError):
+        preflight.poteto_mode_skill_path()
+    assert not preflight._is_claude_dev_env_config_present(ROLE_BUGTEAM)
+
+
 def _install_ok_static_seams(
     monkeypatch: pytest.MonkeyPatch,
     claude_home: Path,

package/scripts/tests/resolve_advisor_model_route.test.mjs

@@ -12,12 +12,12 @@ function runBridge(input) {
     });
 }
 
-test('advisor bridge selects the policy default', () => {
-    const result = runBridge(JSON.stringify({ reasoning_effort: 'xhigh' }));
+test('advisor bridge uses the trusted advisor registration', () => {
+    const result = runBridge(JSON.stringify({ model: 'Astra', reasoning_effort: 'high' }));
     assert.equal(result.status, 0);
     assert.deepEqual(JSON.parse(result.stdout).selected, {
         model: 'gpt-6-astra',
-        effort: 'medium',
+        effort: 'high',
     });
 });
 

package/scripts/tests/test_policy_lint_rules_pairing.py

@@ -182,6 +182,22 @@ def test_pairing_rejects_an_approved_module_without_its_suite(
     assert all_paths == (_APPROVED_PRODUCTION_PATH,)
 
 
+def test_cursor_verifier_constants_require_the_changed_driver_suite(
+    tmp_path: Path,
+) -> None:
+    constants_path = PurePosixPath(
+        ".cursor/skills/verify-claude-dev-env/scripts/verify_installer_constants/constants.mjs"
+    )
+    suite_path = PurePosixPath(
+        ".cursor/skills/verify-claude-dev-env/scripts/verify-installer.test.mjs"
+    )
+    constants_change = _body_change_at(constants_path)
+    assert _diagnostic_paths(tmp_path, constants_change) == (constants_path,)
+    assert _diagnostic_paths(
+        tmp_path, constants_change, _body_change_at(suite_path)
+    ) == ()
+
+
 def test_pairing_rejects_an_unrelated_module_beside_a_changed_approved_suite(
     tmp_path: Path,
 ) -> None:

package/scripts/tests/test_rules.py

@@ -94,8 +94,8 @@ def _comment_policy_surfaces(package_root: Path) -> tuple[Path, ...]:
         package_root / "AGENTS.md",
         package_root / "docs" / "CODE_RULES.md",
         package_root / "system-prompts" / "software-engineer.xml",
-        package_root / ".agents" / "agents" / "clean-coder.md",
-        package_root / ".agents" / "agents" / "code-quality-agent.md",
+        package_root / ".agents" / "agents-archived" / "clean-coder.md",
+        package_root / ".agents" / "agents-archived" / "code-quality-agent.md",
         package_root / "audit-rubrics" / "category_rubrics" / "category-j-code-rules-compliance.md",
         package_root / "audit-rubrics" / "prompts" / "category-j-code-rules-compliance.md",
         package_root / "audit-rubrics" / "category_rubrics" / "category-l-behavior-equivalence.md",
@@ -119,7 +119,7 @@ def _worker_policy_surfaces(package_root: Path) -> tuple[Path, ...]:
         package_root / "AGENTS.md",
         package_root / "docs" / "CODE_RULES.md",
         package_root / "system-prompts" / "software-engineer.xml",
-        package_root / ".agents" / "agents" / "clean-coder.md",
+        package_root / ".agents" / "agents-archived" / "clean-coder.md",
         package_root / ".agents" / "skills" / "grok-spawn" / "reference" / "worker-briefs.md",
         package_root.parent.parent / ".github" / "copilot-instructions.md",
     )
@@ -185,14 +185,14 @@ def _category_l_policy_texts() -> tuple[str, str, str]:
 
 
 def _comment_policy_summary_texts() -> tuple[str, str, str]:
-    clean_coder = _PACKAGE_ROOT / ".agents" / "agents" / "clean-coder.md"
+    clean_coder = _PACKAGE_ROOT / ".agents" / "agents-archived" / "clean-coder.md"
     category_j = (
         _PACKAGE_ROOT
         / "audit-rubrics"
         / "category_rubrics"
         / "category-j-code-rules-compliance.md"
     )
-    code_quality = _PACKAGE_ROOT / ".agents" / "agents" / "code-quality-agent.md"
+    code_quality = _PACKAGE_ROOT / ".agents" / "agents-archived" / "code-quality-agent.md"
     return tuple(
         each_path.read_text(encoding="utf-8").lower()
         for each_path in (clean_coder, category_j, code_quality)

package/scripts/windows/pstack/pstack-command-shim.ps1

@@ -0,0 +1,41 @@
+$command = $args[0]
+$commandArguments = @($args | Select-Object -Skip 1)
+
+if (@("watch-pr", "ship-pr") -notcontains $command) {
+  Write-Error "The command must be watch-pr or ship-pr"
+  exit 1
+}
+
+$codexHome = if ([string]::IsNullOrWhiteSpace($env:CODEX_HOME)) {
+  Join-Path $env:USERPROFILE ".codex"
+} else {
+  $env:CODEX_HOME
+}
+$cacheRoot = Join-Path $codexHome "plugins\cache\pstack-claude\pstack"
+$pluginRoot = Get-ChildItem -LiteralPath $cacheRoot -Directory -ErrorAction SilentlyContinue |
+  Where-Object { $_.Name -match "^\d+\.\d+\.\d+$" } |
+  Sort-Object { [version]$_.Name } -Descending |
+  Select-Object -First 1
+
+if ($null -eq $pluginRoot) {
+  Write-Error "No installed pstack-claude version was found under $cacheRoot"
+  exit 1
+}
+
+$entrypoint = Join-Path $pluginRoot.FullName "skills\poteto-mode\scripts\watch-pr\$command"
+if (-not (Test-Path -LiteralPath $entrypoint -PathType Leaf)) {
+  Write-Error "The pstack entrypoint was not found: $entrypoint"
+  exit 1
+}
+
+$scriptsRoot = Split-Path -Parent (Split-Path -Parent $entrypoint)
+$exitCode = 1
+Push-Location $scriptsRoot
+try {
+  & bun $entrypoint @commandArguments
+  $exitCode = $LASTEXITCODE
+}
+finally {
+  Pop-Location
+}
+exit $exitCode

package/scripts/windows/pstack/ship-pr.cmd

@@ -0,0 +1,3 @@
+@echo off
+pwsh -NoLogo -NoProfile -ExecutionPolicy Bypass -File "%~dp0pstack-command-shim.ps1" ship-pr %*
+exit /b %ERRORLEVEL%

package/scripts/windows/pstack/watch-pr.cmd

@@ -0,0 +1,3 @@
+@echo off
+pwsh -NoLogo -NoProfile -ExecutionPolicy Bypass -File "%~dp0pstack-command-shim.ps1" watch-pr %*
+exit /b %ERRORLEVEL%