claude-dev-env 2.8.0 → 2.9.0

package/scripts/test_grok_patch_artifacts.py

@@ -0,0 +1,82 @@
+"""Behavioral tests for patch artifact extraction and manifests."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from grok_patch_artifacts import (  # noqa: E402
+    compute_sha256_hex,
+    extract_worktree_diff,
+    write_patch_manifest,
+)
+
+
+def _init_repo(path: Path) -> str:
+    subprocess.check_call(["git", "init"], cwd=path, stdout=subprocess.DEVNULL)
+    subprocess.check_call(
+        ["git", "config", "user.email", "test@example.com"], cwd=path, stdout=subprocess.DEVNULL
+    )
+    subprocess.check_call(
+        ["git", "config", "user.name", "test"], cwd=path, stdout=subprocess.DEVNULL
+    )
+    sample = path / "sample.txt"
+    sample.write_text("one\n", encoding="utf-8")
+    subprocess.check_call(["git", "add", "sample.txt"], cwd=path, stdout=subprocess.DEVNULL)
+    subprocess.check_call(
+        ["git", "commit", "-m", "init"], cwd=path, stdout=subprocess.DEVNULL
+    )
+    base = subprocess.check_output(
+        ["git", "rev-parse", "HEAD"], cwd=path, text=True
+    ).strip()
+    sample.write_text("one\ntwo\n", encoding="utf-8")
+    return base
+
+
+def test_write_patch_manifest_binds_hash_paths_and_report(tmp_path: Path) -> None:
+    worktree = tmp_path / "wt"
+    worktree.mkdir()
+    base_sha = _init_repo(worktree)
+    run_dir = tmp_path / "run"
+    report_text = '{"status":"ok"}'
+    manifest = write_patch_manifest(
+        run_state_directory=run_dir,
+        task_id="O-04",
+        base_sha=base_sha,
+        worktree_path=worktree,
+        worker_report_text=report_text,
+    )
+    assert manifest["task_id"] == "O-04"
+    assert manifest["base_sha"] == base_sha
+    assert "sample.txt" in manifest["changed_paths"]
+    patch_path = Path(str(manifest["patch_path"]))
+    assert patch_path.is_file()
+    assert manifest["content_sha256"] == compute_sha256_hex(patch_path.read_bytes())
+    assert manifest["worker_report_sha256"] == compute_sha256_hex(
+        report_text.encode("utf-8")
+    )
+    on_disk = json.loads((run_dir / "patch-manifest.json").read_text(encoding="utf-8"))
+    assert on_disk["content_sha256"] == manifest["content_sha256"]
+
+
+def test_compute_sha256_hex_is_stable() -> None:
+    digest = compute_sha256_hex(b"abc")
+    assert digest == compute_sha256_hex(b"abc")
+    assert digest != compute_sha256_hex(b"abd")
+
+
+def test_extract_worktree_diff_returns_paths(tmp_path: Path) -> None:
+    worktree = tmp_path / "wt"
+    worktree.mkdir()
+    base_sha = _init_repo(worktree)
+    diff_text, all_changed_paths = extract_worktree_diff(
+        worktree_path=worktree, base_sha=base_sha
+    )
+    assert "sample.txt" in all_changed_paths
+    assert "two" in diff_text or "sample" in diff_text

package/scripts/test_grok_run_ledger.py

@@ -0,0 +1,116 @@
+"""Behavioral tests for the host-neutral Grok run ledger."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from dev_env_scripts_constants.grok_run_ledger_constants import (  # noqa: E402
+    TASK_STATUS_ADVISOR_BLOCKED,
+    TASK_STATUS_COMPLETED,
+    TASK_STATUS_PENDING,
+    TASK_STATUS_PENDING_REVIEW,
+)
+from grok_run_ledger import GrokRunLedger, is_legal_status  # noqa: E402
+
+
+def test_register_task_persists_atomically(tmp_path: Path) -> None:
+    ledger = GrokRunLedger(tmp_path)
+    ledger.register_task(task_id="O-04", all_dependencies=())
+    reloaded = GrokRunLedger(tmp_path)
+    record = reloaded.get_task("O-04")
+    assert record.status == TASK_STATUS_PENDING
+    assert is_legal_status(record.status)
+    payload = json.loads((tmp_path / "grok-run-ledger.json").read_text(encoding="utf-8"))
+    assert payload["tasks"][0]["task_id"] == "O-04"
+
+
+def test_dependencies_block_dispatch(tmp_path: Path) -> None:
+    ledger = GrokRunLedger(tmp_path)
+    ledger.register_task(task_id="dep", all_dependencies=())
+    ledger.register_task(task_id="child", all_dependencies=("dep",))
+    assert ledger.can_dispatch("child") is False
+    with pytest.raises(ValueError, match="dependencies"):
+        ledger.mark_in_progress(
+            task_id="child",
+            owner_id="w1",
+            advisor_session_id="s1",
+            base_sha="aaa",
+        )
+    ledger.mark_in_progress(
+        task_id="dep", owner_id="w0", advisor_session_id="s0", base_sha="aaa"
+    )
+    ledger.mark_completed(
+        task_id="dep",
+        reviewed_head="bbb",
+        all_changed_paths=(),
+        advisor_verdict="ENDORSE",
+        all_acceptance_mapping={},
+        all_test_evidence=["ok"],
+    )
+    assert ledger.can_dispatch("child") is True
+
+
+def test_one_live_owner_and_unique_advisor_session(tmp_path: Path) -> None:
+    ledger = GrokRunLedger(tmp_path)
+    ledger.register_task(task_id="a", all_dependencies=())
+    ledger.register_task(task_id="b", all_dependencies=())
+    ledger.mark_in_progress(
+        task_id="a", owner_id="owner", advisor_session_id="sess-a", base_sha="1"
+    )
+    with pytest.raises(ValueError, match="owner already live"):
+        ledger.mark_in_progress(
+            task_id="b", owner_id="owner", advisor_session_id="sess-b", base_sha="1"
+        )
+    with pytest.raises(ValueError, match="advisor session already bound"):
+        ledger.mark_in_progress(
+            task_id="b", owner_id="other", advisor_session_id="sess-a", base_sha="1"
+        )
+
+
+def test_snapshot_drift_moves_to_pending_review(tmp_path: Path) -> None:
+    ledger = GrokRunLedger(tmp_path)
+    ledger.register_task(task_id="t", all_dependencies=())
+    ledger.mark_in_progress(
+        task_id="t", owner_id="w", advisor_session_id="s", base_sha="base"
+    )
+    record = ledger.invalidate_on_snapshot_drift(task_id="t", current_sha="drifted")
+    assert record.status == TASK_STATUS_PENDING_REVIEW
+    assert record.owner_id is None
+
+
+def test_advisor_blocked_terminal(tmp_path: Path) -> None:
+    ledger = GrokRunLedger(tmp_path)
+    ledger.register_task(task_id="t", all_dependencies=())
+    ledger.mark_in_progress(
+        task_id="t", owner_id="w", advisor_session_id="s", base_sha="base"
+    )
+    record = ledger.mark_advisor_blocked(task_id="t", reason="bind failed")
+    assert record.status == TASK_STATUS_ADVISOR_BLOCKED
+    assert "bind failed" in record.test_evidence[0]
+
+
+def test_completed_records_acceptance_and_head(tmp_path: Path) -> None:
+    ledger = GrokRunLedger(tmp_path)
+    ledger.register_task(task_id="t", all_dependencies=())
+    ledger.mark_in_progress(
+        task_id="t", owner_id="w", advisor_session_id="s", base_sha="base"
+    )
+    record = ledger.mark_completed(
+        task_id="t",
+        reviewed_head="head",
+        all_changed_paths=("a.py",),
+        advisor_verdict="ENDORSE",
+        all_acceptance_mapping={"criterion": "evidence"},
+        all_test_evidence=["pytest -q"],
+    )
+    assert record.status == TASK_STATUS_COMPLETED
+    assert record.reviewed_head == "head"
+    assert record.changed_paths == ("a.py",)

package/scripts/test_spawn_grok_batch.py

@@ -1319,3 +1319,298 @@ def test_load_batch_spec_rejects_empty_agent_name(tmp_path: Path) -> None:
 
     with pytest.raises(ValueError, match=WORKER_SPEC_AGENT_NAME_KEY):
         batch.load_batch_spec(specification_path)
+
+# --- O-02 worker advisor contract ---
+
+
+def test_extract_advisor_signal_accepts_four_tokens_only() -> None:
+    assert batch.extract_advisor_signal("ENDORSE\nok") == "ENDORSE"
+    assert batch.extract_advisor_signal("CORRECTION fix path") == "CORRECTION"
+    assert batch.extract_advisor_signal("PLAN later") == "PLAN"
+    assert batch.extract_advisor_signal("STOP") == "STOP"
+    assert batch.extract_advisor_signal("hello ENDORSE") is None
+    assert batch.extract_advisor_signal("") is None
+
+
+def test_load_batch_spec_parses_advisor_block(tmp_path: Path) -> None:
+    header_part, body_part = _write_prompt_parts(tmp_path)
+    payload = _worker_payload(
+        role_name="lens",
+        all_prompt_parts=[str(header_part), str(body_part)],
+        working_directory=tmp_path,
+        tool_profile=TOOL_PROFILE_READONLY,
+    )
+    specification_path = tmp_path / "batch-spec.json"
+    specification_path.write_text(
+        json.dumps(
+            {
+                "role": DEFAULT_ROLE,
+                "should_ping": False,
+                "workers": [payload],
+                "advisor": {
+                    "launcher": "fixture-advisor-launcher",
+                    "model": "opus",
+                    "effort": "high",
+                },
+            }
+        ),
+        encoding=UTF8_ENCODING,
+    )
+    loaded = batch.load_batch_spec(specification_path)
+    assert loaded.advisor is not None
+    assert loaded.advisor.launcher == "fixture-advisor-launcher"
+    assert loaded.advisor.model == "opus"
+    assert loaded.advisor.effort == "high"
+
+
+def test_unique_advisor_sessions_and_completion_verdict(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    header_a, body_a = _write_prompt_parts(tmp_path, role_marker="alpha")
+    header_b, body_b = _write_prompt_parts(tmp_path, role_marker="beta")
+    workers = [
+        _worker_payload(
+            role_name="alpha",
+            all_prompt_parts=[str(header_a), str(body_a)],
+            working_directory=tmp_path,
+            tool_profile=TOOL_PROFILE_BUILD,
+        ),
+        _worker_payload(
+            role_name="beta",
+            all_prompt_parts=[str(header_b), str(body_b)],
+            working_directory=tmp_path,
+            tool_profile=TOOL_PROFILE_BUILD,
+        ),
+    ]
+    specification_path = tmp_path / "batch-spec.json"
+    specification_path.write_text(
+        json.dumps(
+            {
+                "role": DEFAULT_ROLE,
+                "should_ping": False,
+                "workers": workers,
+                "advisor": {
+                    "launcher": "fixture-advisor-launcher",
+                    "model": "opus",
+                    "effort": "high",
+                },
+            }
+        ),
+        encoding=UTF8_ENCODING,
+    )
+    bind_count = {"n": 0}
+    sessions_issued: list[str] = []
+
+    def fake_advisor(
+        *,
+        launcher: str,
+        model: str,
+        effort: str,
+        prompt_text: str,
+        session_id: str | None = None,
+    ) -> tuple[str | None, str, int]:
+        assert launcher == "fixture-advisor-launcher"
+        assert model == "opus"
+        assert effort == "high"
+        if session_id is None:
+            bind_count["n"] += 1
+            session = f"session-{bind_count['n']}"
+            sessions_issued.append(session)
+            return session, "ENDORSE\npre-dispatch ok", 0
+        return session_id, "ENDORSE\npost-report ok", 0
+
+    monkeypatch.setattr(batch, "batch_invoke_advisor", fake_advisor)
+    monkeypatch.setattr(
+        batch,
+        "batch_preflight",
+        lambda **kwargs: PreflightOutcome(is_usable=True, reason=None),
+    )
+    monkeypatch.setattr(batch, "batch_sleep", lambda seconds: None)
+    recorder = _RunnerRecorder(
+        {
+            "alpha": _ok_outcome(),
+            "beta": _ok_outcome(),
+        }
+    )
+    monkeypatch.setattr(batch, "batch_headless_runner", recorder)
+    loaded = batch.load_batch_spec(specification_path)
+    summary = batch.run_grok_batch(
+        batch_spec=loaded, run_state_directory=tmp_path / "run"
+    )
+    assert summary.is_preflight_usable
+    assert len(summary.all_worker_reports) == 2
+    all_session_ids = {
+        each.advisor_session_id for each in summary.all_worker_reports
+    }
+    assert all_session_ids == {"session-1", "session-2"}
+    assert all(
+        each.advisor_completion_signal == "ENDORSE"
+        for each in summary.all_worker_reports
+    )
+    assert all(
+        each.classification != "advisor_blocked"
+        for each in summary.all_worker_reports
+    )
+    for each_report in summary.all_worker_reports:
+        prompt_text = Path(each_report.prompt_path).read_text(encoding=UTF8_ENCODING)
+        assert each_report.advisor_session_id in prompt_text
+
+
+def test_advisor_failure_classifies_advisor_blocked(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    header_part, body_part = _write_prompt_parts(tmp_path, role_marker="solo")
+    payload = _worker_payload(
+        role_name="solo",
+        all_prompt_parts=[str(header_part), str(body_part)],
+        working_directory=tmp_path,
+        tool_profile=TOOL_PROFILE_BUILD,
+    )
+    specification_path = tmp_path / "batch-spec.json"
+    specification_path.write_text(
+        json.dumps(
+            {
+                "role": DEFAULT_ROLE,
+                "should_ping": False,
+                "workers": [payload],
+                "advisor": {"launcher": "fixture-advisor-launcher"},
+            }
+        ),
+        encoding=UTF8_ENCODING,
+    )
+
+    def failing_advisor(**kwargs: object) -> tuple[str | None, str, int]:
+        return None, "", 1
+
+    monkeypatch.setattr(batch, "batch_invoke_advisor", failing_advisor)
+    monkeypatch.setattr(
+        batch,
+        "batch_preflight",
+        lambda **kwargs: PreflightOutcome(is_usable=True, reason=None),
+    )
+    monkeypatch.setattr(batch, "batch_sleep", lambda seconds: None)
+    monkeypatch.setattr(
+        batch,
+        "batch_headless_runner",
+        _RunnerRecorder({"solo": _ok_outcome()}),
+    )
+    loaded = batch.load_batch_spec(specification_path)
+    summary = batch.run_grok_batch(
+        batch_spec=loaded, run_state_directory=tmp_path / "run"
+    )
+    assert len(summary.all_worker_reports) == 1
+    report = summary.all_worker_reports[0]
+    assert report.classification == "advisor_blocked"
+    assert report.is_ok is False
+
+def test_bind_unique_worker_advisor_rejects_placeholder(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def boom(**kwargs: object) -> tuple[str | None, str, int]:
+        raise AssertionError("should not call launcher for placeholder")
+
+    monkeypatch.setattr(batch, "batch_invoke_advisor", boom)
+    with pytest.raises(ValueError, match="placeholder"):
+        batch.bind_unique_worker_advisor(
+            advisor_spec=batch.AdvisorSpec(launcher=batch.DEFAULT_ADVISOR_LAUNCHER_PLACEHOLDER),
+            role_name="lens",
+            all_used_session_ids=set(),
+        )
+
+
+def test_bind_unique_worker_advisor_returns_session(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def fake(**kwargs: object) -> tuple[str | None, str, int]:
+        return "sess-unique-1", "ENDORSE\nok", 0
+
+    monkeypatch.setattr(batch, "batch_invoke_advisor", fake)
+    session_id, signal = batch.bind_unique_worker_advisor(
+        advisor_spec=batch.AdvisorSpec(launcher="fixture-advisor-launcher"),
+        role_name="lens",
+        all_used_session_ids=set(),
+    )
+    assert session_id == "sess-unique-1"
+    assert signal == "ENDORSE"
+
+
+def test_obtain_advisor_completion_verdict_endorses(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def fake(**kwargs: object) -> tuple[str | None, str, int]:
+        return kwargs.get("session_id"), "ENDORSE\nok", 0
+
+    monkeypatch.setattr(batch, "batch_invoke_advisor", fake)
+    signal = batch.obtain_advisor_completion_verdict(
+        advisor_spec=batch.AdvisorSpec(launcher="fixture-advisor-launcher"),
+        role_name="lens",
+        session_id="sess-1",
+        report_text="done",
+    )
+    assert signal == "ENDORSE"
+
+
+def test_invoke_advisor_launcher_builds_command(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    captured: dict[str, object] = {}
+
+    class _Completed:
+        returncode = 0
+        stdout = '{"session_id":"s1","result":"ENDORSE\\nok"}'
+        stderr = ""
+
+    def fake_run(args, **kwargs):  # type: ignore[no-untyped-def]  # subprocess.run stub for argv capture
+        captured["args"] = list(args)
+        captured["input"] = kwargs.get("input")
+        return _Completed()
+
+    monkeypatch.setattr(batch.subprocess, "run", fake_run)
+    session_id, body, code = batch.invoke_advisor_launcher(
+        launcher="fixture-advisor-launcher",
+        model="opus",
+        effort="high",
+        prompt_text="hello",
+    )
+    assert code == 0
+    assert session_id == "s1"
+    assert "ENDORSE" in body
+    assert captured["args"][0] == "fixture-advisor-launcher"
+    assert "--model" in captured["args"]
+
+
+def test_invoke_advisor_launcher_missing_binary_raises_advisor_failure() -> None:
+    try:
+        batch.invoke_advisor_launcher(
+            launcher="__no_such_advisor_launcher_xyz__",
+            model="opus",
+            effort="high",
+            prompt_text="ping",
+        )
+        raise AssertionError("expected AdvisorFailureError")
+    except batch.AdvisorFailureError as raised:
+        assert "not found" in str(raised).lower() or "launcher" in str(raised).lower()
+
+
+def test_invoke_advisor_launcher_passes_timeout(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    captured: dict[str, object] = {}
+
+    class _Completed:
+        returncode = 0
+        stdout = '{"session_id":"s-timeout","result":"ENDORSE\\nok"}'
+        stderr = ""
+
+    def fake_run(args, **kwargs):  # type: ignore[no-untyped-def]  # subprocess.run stub
+        captured["timeout"] = kwargs.get("timeout")
+        return _Completed()
+
+    monkeypatch.setattr(batch.subprocess, "run", fake_run)
+    batch.invoke_advisor_launcher(
+        launcher="fixture-advisor-launcher",
+        model="opus",
+        effort="high",
+        prompt_text="hello",
+    )
+    assert captured["timeout"] == batch.MAXIMUM_ADVISOR_TIMEOUT_SECONDS

package/skills/CLAUDE.md

@@ -17,7 +17,9 @@ Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/
 
 ## Shared support code
 
-`_shared/` — support code used by more than one skill. It holds `pr-loop/`, which provides prompt templates and Python helper scripts shared across the PR-loop skills, and `advisor/`, which provides the shared warm-advisor protocol used by `team-advisor`, `orchestrator`, and `orchestrator-refresh`.
+**`skills/_shared/`** — skill-local PR-loop helpers plus `@` stubs that name
+canonical homes under **`@~/.claude/_shared/`** (advisor protocol, PR-loop
+contracts, runtime scripts). Map: `skills/_shared/CLAUDE.md`. End-of-run gotchas: `skills/_shared/end-of-run-gotcha-recommendations.md`.
 
 ## Skill groups
 
@@ -25,7 +27,7 @@ Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/
 - `anthropic-plan` — creates a source-grounded plan packet before any code changes
 - `orchestrator` — turns the session into the orchestrator: it spawns executor subagents to do the code edits and test runs; hard decisions go to a shared advisor (Claude warm `session-advisor` via SendMessage; a third-party host: max-tier Claude via CLI Claude-chain)
 - `orchestrator-refresh` — sub-skill fired by the `/orchestrator` loop to re-assert the host-matched shared-advisor discipline mid-run (Claude SendMessage; a third-party host's Claude CLI chain, no Agent-tool advisor spawn)
-- `team-advisor` — binds one advisor at the strongest reachable tier (Claude warm agent; a third-party host: max-tier Claude via CLI Claude-chain, fail closed when unreachable) and consults it for a second opinion before a big decision, at completion, when stuck, or when reconsidering the approach
+- `team-advisor` — binds one advisor at the strongest reachable tier (Claude warm agent; a third-party host: max-tier Claude via CLI Claude-chain, fail closed when unreachable); consult cadence and weight live in `docs/references/advisor-tool.md`
 - `grokify` — builds a paste-ready Grok Build handoff with a Claude advisor charter
 - `grok-spawn` — orchestrator playbook for fleets of headless grok CLI workers (preflight, batch spec, `spawn_grok_batch.py`)
 

package/skills/_shared/CLAUDE.md

@@ -1,11 +1,44 @@
-# _shared
+# skills/_shared
 
-Support code shared across multiple skills. Each subdirectory targets a specific cross-skill concern.
+**Map** for skill-install shared assets. Open a stub, then load the `@` target.
+
+## Two homes
+
+| Home | Path | Holds |
+|---|---|---|
+| **Skills shared** | `~/.claude/skills/_shared/` | Converge helpers, end-of-run gotcha ref, and `@` stubs |
+| **Top-level shared** | `~/.claude/_shared/` | Advisor protocol, PR-loop contracts, runtime scripts |
+
+
+## Reference docs (this tree)
+
+| File | Role |
+|---|---|
+| **`end-of-run-gotcha-recommendations.md`** | End-of-run pasteable gotcha protocol for every skill |
 
 ## Subdirectories
 
 | Directory | Role |
 |---|---|
-| `pr-loop/` | Prompt templates and Python helper scripts used by both `bugteam` and `pr-converge` for their audit-fix loop. |
+| **`advisor/`** | Stubs → `@~/.claude/_shared/advisor/` |
+| **`pr-loop/`** | Local converge helpers + stubs → `@~/.claude/_shared/pr-loop/` |
+
+## Canonical-path stubs
+
+| Stub here | Load |
+|---|---|
+| `advisor/advisor-protocol.md` | `@~/.claude/_shared/advisor/advisor-protocol.md` |
+| `advisor/CLAUDE.md` | `@~/.claude/_shared/advisor/CLAUDE.md` |
+| `advisor/scripts/README.md` | `@~/.claude/_shared/advisor/scripts/` |
+| `pr-loop/audit-contract.md` | `@~/.claude/_shared/pr-loop/audit-contract.md` |
+| `pr-loop/audit-reply-template.md` | `@~/.claude/_shared/pr-loop/audit-reply-template.md` |
+| `pr-loop/code-rules-gate.md` | `@~/.claude/_shared/pr-loop/code-rules-gate.md` |
+| `pr-loop/fix-protocol.md` | `@~/.claude/_shared/pr-loop/fix-protocol.md` |
+| `pr-loop/gh-payloads.md` | `@~/.claude/_shared/pr-loop/gh-payloads.md` |
+| `pr-loop/post-audit-thread-contract.md` | `@~/.claude/_shared/pr-loop/post-audit-thread-contract.md` |
+| `pr-loop/precatch-rubric.md` | `@~/.claude/_shared/pr-loop/precatch-rubric.md` |
+| `pr-loop/state-schema.md` | `@~/.claude/_shared/pr-loop/state-schema.md` |
+| `pr-loop/worker-spawn.md` | `@~/.claude/_shared/pr-loop/worker-spawn.md` |
+| `pr-loop/scripts/RUNTIME_SCRIPTS.md` | `@~/.claude/_shared/pr-loop/scripts/` |
 
-Files here are not skills themselves and have no `SKILL.md`. They install alongside each consuming skill via the install pipeline in `packages/claude-dev-env/bin/install.mjs`.
+Install via `packages/claude-dev-env/bin/install.mjs`.

package/skills/_shared/advisor/CLAUDE.md

@@ -0,0 +1,9 @@
+# Advisor
+
+**Canonical home:**
+
+@~/.claude/_shared/advisor/CLAUDE.md
+
+@~/.claude/_shared/advisor/advisor-protocol.md
+
+Scripts: `~/.claude/_shared/advisor/scripts/` (`model_tier_run_validator.py`, `tier_model_ids.py`, constants under `scripts/config/`).

package/skills/_shared/advisor/advisor-protocol.md

@@ -0,0 +1,5 @@
+# Advisor protocol
+
+**Canonical home:**
+
+@~/.claude/_shared/advisor/advisor-protocol.md

package/skills/_shared/advisor/scripts/README.md

@@ -0,0 +1,9 @@
+# Advisor scripts
+
+**Canonical home:**
+
+@~/.claude/_shared/advisor/scripts/model_tier_run_validator.py
+
+@~/.claude/_shared/advisor/scripts/tier_model_ids.py
+
+Full tree: `~/.claude/_shared/advisor/scripts/`.