claude-dev-env 8.21.0 → 8.23.0

package/hooks/session/test_advisor_rules_prompt.py

@@ -0,0 +1,86 @@
+"""Tests for advisor_rules_prompt: SessionStart hook that injects advisor consult rules."""
+
+import json
+import sys
+from io import StringIO
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+_SESSION_DIR = Path(__file__).resolve().parent
+_HOOKS_ROOT = _SESSION_DIR.parent
+_ADVISOR_TOOL_DOC = _HOOKS_ROOT.parent / "docs" / "references" / "advisor-tool.md"
+for each_sys_path_entry in (str(_SESSION_DIR), str(_HOOKS_ROOT)):
+    if each_sys_path_entry not in sys.path:
+        sys.path.insert(0, each_sys_path_entry)
+
+import advisor_rules_prompt as starter
+
+from hooks_constants.advisor_rules_prompt_constants import (
+    ADVISOR_DISABLE_ENV_VAR,
+    ADVISOR_RULES_PROMPT,
+    ALL_ADVISOR_RULE_SENTENCES,
+    CLAUDE_CONFIG_DIR_ENV_VAR,
+)
+
+
+def _run_main() -> str:
+    captured_stdout = StringIO()
+    with patch("sys.stdout", captured_stdout):
+        starter.main()
+    return captured_stdout.getvalue()
+
+
+@pytest.fixture
+def config_directory(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    monkeypatch.setenv(CLAUDE_CONFIG_DIR_ENV_VAR, str(tmp_path))
+    monkeypatch.delenv(ADVISOR_DISABLE_ENV_VAR, raising=False)
+    return tmp_path
+
+
+def _write_settings(config_directory: Path, settings: object) -> None:
+    (config_directory / "settings.json").write_text(json.dumps(settings), encoding="utf-8")
+
+
+class TestAdvisorRulesPrompt:
+    def test_should_emit_rules_when_advisor_model_is_set(self, config_directory: Path) -> None:
+        _write_settings(config_directory, {"advisorModel": "fable"})
+        hook_output = json.loads(_run_main())["hookSpecificOutput"]
+        assert hook_output["hookEventName"] == "SessionStart"
+        assert hook_output["additionalContext"] == ADVISOR_RULES_PROMPT
+
+    def test_should_emit_nothing_when_advisor_model_is_missing(
+        self, config_directory: Path
+    ) -> None:
+        _write_settings(config_directory, {"permissions": {}})
+        assert _run_main() == ""
+
+    def test_should_emit_nothing_when_advisor_model_is_blank(self, config_directory: Path) -> None:
+        _write_settings(config_directory, {"advisorModel": "  "})
+        assert _run_main() == ""
+
+    def test_should_emit_nothing_when_settings_file_is_absent(self, config_directory: Path) -> None:
+        assert _run_main() == ""
+
+    def test_should_emit_nothing_when_settings_file_is_not_json(
+        self, config_directory: Path
+    ) -> None:
+        (config_directory / "settings.json").write_text("{not json", encoding="utf-8")
+        assert _run_main() == ""
+
+    def test_should_emit_nothing_when_environment_disables_the_advisor(
+        self, config_directory: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        _write_settings(config_directory, {"advisorModel": "fable"})
+        monkeypatch.setenv(ADVISOR_DISABLE_ENV_VAR, "1")
+        assert _run_main() == ""
+
+
+class TestAdvisorRulesMatchTheDoc:
+    @pytest.mark.parametrize("each_rule_sentence", ALL_ADVISOR_RULE_SENTENCES)
+    def test_should_quote_each_sentence_from_advisor_tool_doc(
+        self, each_rule_sentence: str
+    ) -> None:
+        doc_text = " ".join(_ADVISOR_TOOL_DOC.read_text(encoding="utf-8").split())
+        assert each_rule_sentence in doc_text

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.21.0",
+    "version": "8.23.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/asd-ste100-language.md

@@ -26,6 +26,7 @@ definitions and dictionary decisions.
 - Use inclusive, neutral language.
 - Use periods, commas, colons, and bullets to show structure.
 - Preserve exact quoted labels, identifiers, formulas, titles, and interface text.
+- Send the reader only a result, a blocker, or a question. Leave out a line that says nothing is needed from them, and leave out which agent, session, or coordinator did the work.
 - Use `WARNING` for a risk of injury or death. Use `CAUTION` for a risk of equipment, tool, or machine damage. State the command or condition first, then state the result.
 - Aim for 20 words or fewer in a procedure sentence when the technical content allows.
 - Aim for 25 words or fewer in a descriptive sentence when the technical content allows.

package/rules/ci-owns-the-gate.md

@@ -64,6 +64,34 @@ A cache stays available on one condition. CI derives the key itself from the
 tree it is about to test, looks for a previous run under that key, and
 republishes that result. CI computes, CI verifies, CI decides.
 
+## A repository that runs no CI
+
+An owner can rule that a repository spends no CI minutes. There the local gate
+is the gate, and the agent that drives the pull request runs it on every head
+it asks to merge. The repository carries the gate as a `cde verify` manifest at
+`.claude/local-gate.json`: tests with collection floors, and lint.
+
+1. Check out the pull request head with a clean tree and fetch its base.
+2. Run the manifest against the base commit the pull request names:
+
+   ```
+   python <cde>/scripts/local_verification/cli.py --manifest .claude/local-gate.json --repo . --base <base sha> --output <outside the repository>/report.json
+   ```
+
+3. Publish the report:
+
+   ```
+   python <cde>/scripts/local_report_publisher.py --token-environment GH_TOKEN --repository <owner>/<name> --pull-number <number> --local-repo . --manifest .claude/local-gate.json --report <outside the repository>/report.json
+   ```
+
+The publisher checks the report against the manifest digest, the clean tree,
+and the live head and base, then posts the `local-checks` commit status. A
+report that fails any of those posts a failure or an error. The branch ruleset
+lists `local-checks` as a required status check, so the host refuses a merge
+until a passing report covers the head, and `agent_merge_check.py` prints
+`HOLD` on the same requirement. A push moves the head and leaves the status
+behind, so each new head runs the gate again.
+
 ## Sibling rules
 
 | Rule | Role |

package/rules/memory-stores-durable-facts.md

@@ -0,0 +1,57 @@
+# Memory Stores Durable Facts
+
+**When this applies:** Before you write or update a file in an auto-memory
+directory, and before you add its line to `MEMORY.md`.
+
+## Rule
+
+A memory must still help a fresh session, with no context, weeks later.
+
+Run one test on the draft. Strip every date, pull request number, issue number,
+commit, job path, session ID, and task number. When what remains is empty or
+false, the draft is run state. Put it in the task tracker, the pull request, or
+a handoff file beside the work, and save no memory.
+
+## What never becomes a memory
+
+| Shape | Example | Where it belongs |
+|---|---|---|
+| Run or program state | "paused at", "resume from", "4 of 11 merged", a pointer to a handoff file | The task tracker or the handoff file |
+| A pull request, issue, stack, or commit map | "#583, #605, #610 merged" | The epic issue or the pull request |
+| A temporary condition | A concurrency schedule, credits out, a fleet that works this week, a fix "until X lands" | The current conversation |
+| One session's topology | A session ID, a parallel session's worktree, a second-account dispatch setup | The current conversation |
+| A workaround for a hook, gate, or verifier as it behaved one day | "the minter never fires, so skip the check" | A fix to the hook, per [`correction-lens.md`](correction-lens.md) |
+| The story of one incident or bug fix | "the fold checkbox took five tries" | Git history and the pull request body |
+| Where code lives, or a design recipe for one build phase | A module layout, a prompt recipe for one engine version | The repository and its inventories |
+| A restatement of a rule file | "CI owns the gate" | The rule file already loaded |
+
+## What a memory holds
+
+- A preference or standing order the user stated, with the date the user set it.
+- A trap in the local setup or the platform that stays true, such as a shared
+  `rr-cache` that replays one-sided resolutions without a marker.
+- A pointer to an external resource: a dashboard, a repository, a tracker.
+
+Write the fact first. A date belongs only on a rule the user set on that date.
+
+## Keeping the folder current
+
+When a memory goes stale, delete it and its `MEMORY.md` line in the same run.
+A "superseded" note on a stale memory keeps a false fact loading into every
+session.
+
+## Why
+
+One project's memory folder held 104 index entries. A cleanup pass removed 57
+of them, and each one failed the test above. Handoffs outlived their work,
+pull request maps named merged branches, and a capacity schedule and a
+dispatch topology contradicted newer standing orders. Every stale memory loads
+into each session and reads as current.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`correction-lens.md`](correction-lens.md) | A memory records a decision, and the control holds the behavior |
+| [`verify-before-asking.md`](verify-before-asking.md) | A recalled fact is a claim to re-check |
+| [`cleanup-temp-files.md`](cleanup-temp-files.md) | Scratch output leaves with the task |

package/rules/review-closure-is-a-check.md

@@ -25,6 +25,7 @@ It prints `CLOSED` and exits 0 when every finding on the head is answered. It pr
 | A thread the driving account opened | Itself |
 | A blocking `Claude Approvals` row | A push, which moves the head the check reports on |
 | A top-level comment on the pull request | A later top-level comment from the driving account |
+| A bot notice: a review-skipped note, a pointer to an updated summary, a Graphite verdict mirror, a Qodo change summary, a Qodo in-progress placeholder, or a Qodo review that found no issues | Itself |
 
 A review bot rewrites its summary comment on each pass. Its edit leaves an answered summary closed, because each new finding it has arrives as a review thread or a new comment. An edit from a person reopens the comment.
 

package/scripts/dev_env_scripts_constants/grok_worker_constants.py

@@ -87,12 +87,16 @@ ROLE_BUGTEAM: str = "bugteam"
 ROLE_CLEAN_CODER: str = "clean-coder"
 """Compatibility role for FIX and standards-fix using poteto-agent."""
 
+ROLE_TRANSLATOR: str = "translator"
+"""Role the shared_utils translation chain dispatches, served by 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: ("poteto-agent.md",),
     ROLE_CLEAN_CODER: ("poteto-agent.md",),
+    ROLE_TRANSLATOR: ("poteto-agent.md",),
 }
 """Agent definition filenames required under ``agents/`` for each known role."""
 

package/scripts/dev_env_scripts_constants/review_closure_constants.py

@@ -137,6 +137,19 @@ USER_TYPE_KEY: str = "type"
 BOT_USER_TYPE: str = "Bot"
 """The user type GitHub reports for an app account such as a review bot."""
 
+ALL_NOTICE_COMMENT_MARKERS: tuple[str, ...] = (
+    "No code changes since the last review",
+    "was updated up to the latest commit",
+    "<!-- graphite-review-comment -->",
+    "<h3>PR Summary by Qodo</h3>",
+    "<h3>Qodo is busy working</h3>",
+    "<h3>Great, no issues found!</h3>",
+)
+"""Text a bot notice carries: a Qodo skip note, a Qodo pointer to its updated
+summary, a Graphite verdict mirror whose findings arrive as review threads, a
+Qodo description of the change, a Qodo placeholder posted while it reviews, and
+a Qodo review that found nothing."""
+
 SHORT_SHA_LENGTH: int = 7
 """How much of a commit identifier the verdict line prints."""
 

package/scripts/dev_env_scripts_constants/shared_tree_constants.py

@@ -12,5 +12,9 @@ PROCESS_TREE_DIRECTORY_NAME: str = "process-tree"
 
 PROCESS_TREE_KILL_MODULE_FILENAME: str = "process_tree_kill.py"
 
+ADVISOR_DIRECTORY_NAME: str = "advisor"
+
+TIER_MODEL_IDS_MODULE_FILENAME: str = "tier_model_ids.py"
+
 AGENTS_DIRECTORY_SUFFIX: str = ".agents"
 DEFAULT_MANAGED_ROOT_NAME: str = ".claude"

package/scripts/invoke_code_review.py

@@ -26,6 +26,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import subprocess
 import sys
 from collections.abc import Callable, Sequence
@@ -41,8 +42,10 @@ sys.path[:] = [
 ]
 sys.path[:0] = [_scripts_directory]
 
+from shared_tree_paths import resolve_shared_advisor_scripts_directory
+
 _advisor_scripts_path = str(
-    _scripts_directory_path.parent / "_shared" / "advisor" / "scripts"
+    resolve_shared_advisor_scripts_directory(__file__, all_environment=os.environ)
 )
 sys.path[:] = [
     each_existing_entry

package/scripts/local_report_cli.py

@@ -2,16 +2,16 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import sys
 from collections.abc import Mapping, Sequence
-from dataclasses import dataclass
 from pathlib import Path
 from typing import TextIO
 
 from local_report_core import PublicationOutcome, publish_local_report
 from local_verification.config import SUCCESS_EXIT_CODE
 from pr_verification.config.constants import GIT_BARE_SUFFIX, GITHUB_API_URL
-from pr_verification.github import GitHubAppAuthenticator, GitHubError
+from pr_verification.github import GitHubApi, GitHubAppAuthenticator, GitHubError
 from pr_verification.model import RepositorySettings
 
 
@@ -34,8 +34,7 @@ def main(
     parser = _build_parser()
     parsed_arguments = parser.parse_args(list(all_arguments))
     try:
-        settings = _load_settings(parsed_arguments)
-        outcome = _publish_from_settings(settings, parsed_arguments)
+        outcome = _publish_from_arguments(parsed_arguments)
     except (OSError, TypeError, ValueError, GitHubError) as error:
         stderr.write(f"{error}\n")
         return 3
@@ -43,31 +42,57 @@ def main(
     return SUCCESS_EXIT_CODE
 
 
-def _publish_from_settings(
-    settings: _PublisherSettings, parsed_arguments: argparse.Namespace
-) -> PublicationOutcome:
-    repository = RepositorySettings(
-        settings.repository, settings.repository + GIT_BARE_SUFFIX
+def _publish_from_arguments(parsed_arguments: argparse.Namespace) -> PublicationOutcome:
+    all_settings = _read_settings_file(parsed_arguments.settings)
+    api_url = _required_setting(
+        parsed_arguments.api_url, all_settings, "api_url", GITHUB_API_URL
     )
-    authenticator = GitHubAppAuthenticator(
-        settings.api_url,
-        settings.app_id,
-        settings.installation_id,
-        settings.private_key_path,
+    repository_slug = _required_repository_setting(
+        parsed_arguments.repository, all_settings
     )
-    github = authenticator.issue_repository_api(
-        repository, should_write_issue_labels=True
+    pull_request_number = _required_integer_setting(
+        parsed_arguments.pull_number, all_settings, "pull_number"
     )
+    repository = RepositorySettings(repository_slug, repository_slug + GIT_BARE_SUFFIX)
+    github = _issue_repository_api(parsed_arguments, all_settings, api_url, repository)
     return publish_local_report(
         github,
         repository,
-        settings.pull_request_number,
+        pull_request_number,
         parsed_arguments.local_repo,
         parsed_arguments.manifest,
         parsed_arguments.report,
     )
 
 
+def _issue_repository_api(
+    parsed_arguments: argparse.Namespace,
+    all_settings: Mapping[str, object],
+    api_url: str,
+    repository: RepositorySettings,
+) -> GitHubApi:
+    if parsed_arguments.token_environment is not None:
+        return GitHubApi(api_url, _environment_token(parsed_arguments.token_environment))
+    authenticator = GitHubAppAuthenticator(
+        api_url,
+        _required_integer_setting(parsed_arguments.app_id, all_settings, "app_id"),
+        _required_integer_setting(
+            parsed_arguments.installation_id, all_settings, "installation_id"
+        ),
+        _required_path_setting(parsed_arguments.private_key_path, all_settings),
+    )
+    return authenticator.issue_repository_api(
+        repository, should_write_issue_labels=True
+    )
+
+
+def _environment_token(variable_name: str) -> str:
+    token = os.environ.get(variable_name)
+    if not token:
+        raise TypeError(f"Missing publisher token in environment variable: {variable_name}")
+    return token
+
+
 def _outcome_mapping(outcome: PublicationOutcome) -> dict[str, object]:
     return {
         "status": outcome.status.value,
@@ -76,16 +101,6 @@ def _outcome_mapping(outcome: PublicationOutcome) -> dict[str, object]:
     }
 
 
-@dataclass(frozen=True)
-class _PublisherSettings:
-    api_url: str
-    app_id: int
-    installation_id: int
-    private_key_path: Path
-    repository: str
-    pull_request_number: int
-
-
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="cde publish-local-report")
     parser.add_argument("--settings", type=Path)
@@ -93,6 +108,7 @@ def _build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--app-id", type=int)
     parser.add_argument("--installation-id", type=int)
     parser.add_argument("--private-key-path", type=Path)
+    parser.add_argument("--token-environment")
     parser.add_argument("--repository")
     parser.add_argument("--pull-number", type=int)
     parser.add_argument("--local-repo", type=Path, required=True)
@@ -101,32 +117,13 @@ def _build_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def _load_settings(parsed_arguments: argparse.Namespace) -> _PublisherSettings:
-    all_settings: Mapping[str, object] = {}
-    if parsed_arguments.settings is not None:
-        parsed_settings = json.loads(
-            parsed_arguments.settings.read_text(encoding="utf-8")
-        )
-        if not isinstance(parsed_settings, Mapping):
-            raise ValueError("Publisher settings must be an object")
-        all_settings = parsed_settings
-    return _PublisherSettings(
-        _required_setting(
-            parsed_arguments.api_url,
-            all_settings,
-            "api_url",
-            GITHUB_API_URL,
-        ),
-        _required_integer_setting(parsed_arguments.app_id, all_settings, "app_id"),
-        _required_integer_setting(
-            parsed_arguments.installation_id, all_settings, "installation_id"
-        ),
-        _required_path_setting(parsed_arguments.private_key_path, all_settings),
-        _required_repository_setting(parsed_arguments.repository, all_settings),
-        _required_integer_setting(
-            parsed_arguments.pull_number, all_settings, "pull_number"
-        ),
-    )
+def _read_settings_file(settings_path: Path | None) -> Mapping[str, object]:
+    if settings_path is None:
+        return {}
+    parsed_settings = json.loads(settings_path.read_text(encoding="utf-8"))
+    if not isinstance(parsed_settings, Mapping):
+        raise ValueError("Publisher settings must be an object")
+    return parsed_settings
 
 
 def _required_setting(

package/scripts/policy_lint/adapter_configuration.py

@@ -128,6 +128,8 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
 
         hooks/blocking/bash_pre_tool_use_dispatcher.py   -> exempt
         hooks/blocking/step_note_gate.py                 -> exempt
+        hooks/blocking/reply_length_gate.py              -> exempt
+        hooks/blocking/edit_marker_gate.py               -> exempt
         hooks/blocking/some_new_blocker.py               -> flagged
 
     The Bash PreToolUse dispatcher sits under ``blocking/`` for layout reasons
@@ -137,6 +139,12 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
     The step-note gate allows every call until the user runs ``/step-notes on``.
     It asks for a readable status line and decides no code or safety policy.
 
+    The reply length gate caps the sentences in a chat reply to the user. It
+    decides the shape of prose and no code or safety policy.
+
+    The edit marker gate keeps strikethrough and edit notes out of an edited
+    chat message. It decides the shape of prose and no code or safety policy.
+
     Args:
         registered_string: One command, path, script, or entrypoint string.
     """

package/scripts/policy_lint/config/constants.py

@@ -64,6 +64,8 @@ ALL_ACTION_BOUNDARY_PREFIXES = ("deny_", "block_", "ask_")
 ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/bash_pre_tool_use_dispatcher.py",
     "blocking/step_note_gate.py",
+    "blocking/reply_length_gate.py",
+    "blocking/edit_marker_gate.py",
 )
 ALL_TEST_DIRECTORY_NAMES = frozenset({"tests"})
 ALL_TEST_FILE_PREFIXES = ("test_",)

package/scripts/resolve_worker_spawn.py

@@ -24,6 +24,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import subprocess
 import sys
 from collections.abc import Callable, Sequence
@@ -40,8 +41,10 @@ sys.path[:] = [
 ]
 sys.path[:0] = [_scripts_directory]
 
+from shared_tree_paths import resolve_shared_advisor_scripts_directory
+
 _advisor_scripts_path = str(
-    _scripts_directory_path.parent / "_shared" / "advisor" / "scripts"
+    resolve_shared_advisor_scripts_directory(__file__, all_environment=os.environ)
 )
 sys.path[:] = [
     each_existing_entry

package/scripts/review_closure_model.py

@@ -15,12 +15,16 @@ and the approvals conclusion, and name what waits.
     top-level: a bot comment, then an agent one -> closed
     top-level: the bot edits after that reply   -> closed
     top-level: a person edits after that reply  -> open
+    top-level: a bot notice with no finding     -> closed
 
 A red circle marks a finding a review states as blocking, so resolution alone
 leaves it open. The reply says what changed, or why the finding stands.
 A review bot rewrites its summary comment on each pass, and any new finding it
 has arrives as a review thread or a new comment, so its edit alone reopens
-nothing.
+nothing. A bot notice carries a skip note, a pointer to an updated summary, a
+verdict mirror, a description of the change, a placeholder posted while the bot
+reviews, or a review that found nothing, and never a finding, so it waits on
+nobody.
 """
 
 from __future__ import annotations
@@ -33,6 +37,7 @@ from dev_env_scripts_constants.review_closure_constants import (
     ALL_BLOCKING_CONCLUSIONS,
     ALL_COMMENT_AUTHOR_KEYS,
     ALL_COMMENT_LIST_KEYS,
+    ALL_NOTICE_COMMENT_MARKERS,
     ALL_OUTDATED_KEYS,
     ALL_RESOLVED_KEYS,
     APPROVALS_CHECK_NAME,
@@ -93,6 +98,7 @@ class TopLevelComment:
     identifier: object
     author_login: str
     is_bot: bool
+    is_notice: bool
     created_at: datetime
     updated_at: datetime
     url: str
@@ -217,7 +223,7 @@ def top_level_finding(
     Returns:
         The finding this comment leaves open, or None when it is answered.
     """
-    if comment.author_login in all_driver_logins:
+    if comment.author_login in all_driver_logins or comment.is_notice:
         return None
     last_counted_at = comment.created_at if comment.is_bot else comment.updated_at
     if latest_driver_time is not None and last_counted_at <= latest_driver_time:
@@ -423,6 +429,9 @@ def parse_top_level_comment(
 ) -> TopLevelComment:
     """Read one top-level comment from the REST answer.
 
+    A bot comment whose body carries a notice marker is a notice. A person's
+    comment carrying the same text still counts, since anyone can paste it.
+
     Args:
         all_comment_fields: The comment as the issue comments route reports it.
 
@@ -432,10 +441,14 @@ def parse_top_level_comment(
     Raises:
         ValueError: A timestamp is missing or does not parse.
     """
+    is_bot = _is_bot_author(all_comment_fields)
+    body = str(all_comment_fields.get(COMMENT_BODY_KEY) or "")
     return TopLevelComment(
         identifier=all_comment_fields.get(COMMENT_IDENTIFIER_KEY),
         author_login=_comment_author_login(all_comment_fields),
-        is_bot=_is_bot_author(all_comment_fields),
+        is_bot=is_bot,
+        is_notice=is_bot
+        and any(each_marker in body for each_marker in ALL_NOTICE_COMMENT_MARKERS),
         created_at=datetime.fromisoformat(str(all_comment_fields.get(CREATED_AT_KEY))),
         updated_at=datetime.fromisoformat(str(all_comment_fields.get(UPDATED_AT_KEY))),
         url=str(all_comment_fields.get(HTML_URL_KEY) or ""),

package/scripts/shared_tree_paths.py

@@ -11,6 +11,7 @@ from collections.abc import Mapping
 from pathlib import Path
 
 from dev_env_scripts_constants.shared_tree_constants import (
+    ADVISOR_DIRECTORY_NAME,
     AGENTS_DIRECTORY_SUFFIX,
     CLAUDE_CONFIG_DIR_ENV_VAR,
     DEFAULT_MANAGED_ROOT_NAME,
@@ -18,6 +19,7 @@ from dev_env_scripts_constants.shared_tree_constants import (
     PROCESS_TREE_KILL_MODULE_FILENAME,
     SCRIPTS_DIRECTORY_NAME,
     SHARED_PACKAGE_DIRECTORY_NAME,
+    TIER_MODEL_IDS_MODULE_FILENAME,
 )
 
 
@@ -131,3 +133,28 @@ def resolve_shared_process_tree_scripts_directory(
         PROCESS_TREE_KILL_MODULE_FILENAME,
         1,
     )
+
+
+def resolve_shared_advisor_scripts_directory(
+    module_file: str | Path,
+    all_environment: Mapping[str, str],
+) -> Path:
+    """Return the advisor scripts directory that holds the tier model ids.
+
+    Names the advisor sub-package for a caller sitting one level under the
+    installed root, such as a dispatcher in the managed ``scripts`` directory.
+
+    Args:
+        module_file: Path of the importing module (``__file__``).
+        all_environment: Mapping that may hold ``CLAUDE_CONFIG_DIR``.
+
+    Returns:
+        Directory that should hold ``tier_model_ids.py``.
+    """
+    return resolve_shared_scripts_directory(
+        module_file,
+        all_environment,
+        ADVISOR_DIRECTORY_NAME,
+        TIER_MODEL_IDS_MODULE_FILENAME,
+        1,
+    )

package/scripts/test_resolve_worker_spawn.py

@@ -56,6 +56,7 @@ from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
     REASON_GROK_AUTH_FAILED,
     REASON_PROMPT_FILE_MISSING,
     REASON_TIMEOUT_OUT_OF_BOUNDS,
+    ROLE_TRANSLATOR,
     RESULT_KEY_ATTEMPTS,
     RESULT_KEY_OK,
     RESULT_KEY_OUTPUT,
@@ -865,6 +866,33 @@ def test_tier_three_argv_includes_agent_for_default_role(
     )
 
 
+def test_translator_role_dispatches_the_poteto_agent_on_tier_three(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    prompt_file, working_directory, run_state_directory = _paths(tmp_path)
+    call_log = _install_seams(
+        monkeypatch,
+        grok_outcome=_grok_failure(CLASSIFICATION_AUTH_FAILURE),
+        claude_outcome=_claude_served(),
+        host_profile=HOST_PROFILE_CLAUDE,
+    )
+
+    spawn_outcome = dispatcher.resolve_worker_spawn(
+        role=ROLE_TRANSLATOR,
+        prompt_file=prompt_file,
+        working_directory=working_directory,
+        timeout_seconds=DEFAULT_WORKER_TIMEOUT_SECONDS,
+        is_claude_tier_enabled=True,
+        run_state_directory=run_state_directory,
+    )
+
+    assert spawn_outcome.tier_used == TIER_CLAUDE_HEADLESS
+    assert call_log.claude_arguments is not None
+    agent_flag_index = call_log.claude_arguments.index(AGENT_FLAG)
+    assert call_log.claude_arguments[agent_flag_index + 1] == "poteto-agent"
+    assert ROLE_TRANSLATOR not in call_log.claude_arguments
+
+
 def test_large_prompt_stays_out_of_claude_argv(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None: