claude-dev-env 8.3.0 → 8.4.0

package/.agents/skills/team-advisor/SKILL.md

@@ -16,8 +16,8 @@ One warm advisor at the strongest tier this session can reach. This session is t
 
 | Doc | Holds |
 |---|---|
-| [`docs/references/advisor-tool.md`](../../docs/references/advisor-tool.md) | **Consult cadence and weight.** When to call, the hard rule before first write, and how to treat advice. Read this for every consult. |
-| [`~/.claude/_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md) | **Bind and lifecycle.** Session identity, host detect, model floor, warm-up, CLI fallback. Its read map routes each moment to a `reference/` detail file. |
+| [`docs/references/advisor-tool.md`](../../../docs/references/advisor-tool.md) | **Consult cadence and weight.** When to call, the hard rule before first write, and how to treat advice. Read this for every consult. |
+| [`~/.claude/_shared/advisor/advisor-protocol.md`](../../../_shared/advisor/advisor-protocol.md) | **Bind and lifecycle.** Session identity, host detect, model floor, warm-up, CLI fallback. Its read map routes each moment to a `reference/` detail file. |
 | Installed `poteto-mode` skill | **Reply contract.** The advisor prompt carries ENDORSE / CORRECTION / PLAN / STOP. |
 | [`reference/advisor-docs-review.md`](reference/advisor-docs-review.md) | Anthropic advisor-tool source facts: measured effects, Sonnet steering, cost levers, failure modes. Background. Read it when tuning the bind, not on every consult. |
 
@@ -29,7 +29,7 @@ One warm advisor at the strongest tier this session can reach. This session is t
 4. Skip the multi-consumer "who you are" opener. This session is the sole consumer.
 5. When the bind or reply path fails, fail closed and report to the user. On a third-party host, only the bound advisor issues ENDORSE / CORRECTION / PLAN / STOP.
 
-**GOTCHA (Cursor / ThirdParty + Astra):** when the walk reaches Astra or the user asks for Astra, first tool call is `python ~/.claude/_shared/advisor/scripts/codex_astra_advisor.py --bind --enable-astra --cwd <repo-root>` with the charter on stdin. Do not use Agent or Task. Do not search for a probe path. Details: [`third-party-bind.md`](../../_shared/advisor/reference/third-party-bind.md) GOTCHA and [`astra-rung.md`](../../_shared/advisor/reference/astra-rung.md).
+**GOTCHA (Cursor / ThirdParty + Astra):** when the walk reaches Astra or the user asks for Astra, first tool call is `python ~/.claude/_shared/advisor/scripts/codex_astra_advisor.py --bind --enable-astra --cwd <repo-root>` with the charter on stdin. Do not use Agent or Task. Do not search for a probe path. Details: [`third-party-bind.md`](../../../_shared/advisor/reference/third-party-bind.md) GOTCHA and [`astra-rung.md`](../../../_shared/advisor/reference/astra-rung.md).
 
 Full walk, charter, consult packet, Astra routing, and drift re-bind live in the protocol read map and its `reference/` files.
 
@@ -37,7 +37,7 @@ Full walk, charter, consult packet, Astra routing, and drift re-bind live in the
 
 Follow **When to call**, **Hard rule**, and **How to treat advice** in `advisor-tool.md`.
 
-Build every first brief with [`_shared/advisor/reference/consult-format.md`](../../_shared/advisor/reference/consult-format.md). Later briefs carry only the delta and changed evidence.
+Build every first brief with [`_shared/advisor/reference/consult-format.md`](../../../_shared/advisor/reference/consult-format.md). Later briefs carry only the delta and changed evidence.
 
 With the built-in advisor tool, call `advisor()` with no brief. The tool forwards the whole transcript. Its reply is free text, not one of the four signal words, so weigh it per **How to treat advice** in `advisor-tool.md`.
 
@@ -48,3 +48,8 @@ Aim for two consults on a normal task: one after orientation and one after write
 - One bind per session; this session owns the built-in tool choice, spawn, in-session Astra spawn, or CLI bind, drift re-bind, and shutdown.
 - Bind at or above the protocol floor for this host.
 - The advisor only answers (messaging); the session runs tools and posts.
+- Keep an optional reference gap in the reference record: path, status, repair action, and repair result. A reference gap leaves bind status separate.
+- On Codex, select native Astra when its bind and reply validation pass. Record `selected_tier: Astra` and `reply_path: native`.
+- Mark `fallback_kind: broken` only when the selected bind or reply path fails. Record the selected tier, fallback reason, and reply path in the same evidence object.
+- Record first, recovery, and completion consults with changed evidence, validation, unresolved risks, and report-back status.
+- Write the evidence object to the session-controlled `model-tier-run.json` record described in `advisor-tool.md`.

package/_shared/advisor/reference/spawn-walk-log.md

@@ -12,6 +12,7 @@ Write the log as JSON with these field names:
 - `astra_enabled`: a boolean recorded before candidate selection. On Claude and ThirdParty, `true` adds Astra after Fable and `false` walks Fable alone. On Codex this flag does not change the walk.
 - `attempts`: one `{tier, result}` entry appended as each bind try happens. `result` is `codex` for an Astra helper bind, `spawned` for an in-session spawn (Claude Agent or Codex native Astra), `cli` for a CLI Claude-chain bind, or a failure reason such as `unavailable`.
 - `selected_tier`: the tier of the first successful bind (first `codex`, `spawned`, or `cli` entry), or `null` paired with a `fallback_reason` string when none bound.
+- `evidence`: the versioned reference, fallback, and consult record described in `docs/references/advisor-tool.md`. A reference status records optional path repair separately from bind status.
 
 ## Log path
 
@@ -28,5 +29,5 @@ Exit code `1` means a ladder invariant failed.
 Exit code `2` means the path or JSON was unusable.
 The same checks are available in-process via `validate_model_tier_run(run)`.
 
-The validator checks ladder shape only: the candidate slice, the order of bind tries, and the success-token rules per tier and host. On Claude and ThirdParty, Astra is attempted after Fable when `astra_enabled` is true, and `selected_tier: "Astra"` requires `result: "codex"`. On Codex, the walk is Astra only, and `result: "spawned"` or `result: "codex"` counts as success.
+The validator checks ladder shape and validates `evidence` when it is present. On Claude and ThirdParty, Astra is attempted after Fable when `astra_enabled` is enabled, and `selected_tier: "Astra"` requires `result: "codex"`. On Codex, the walk is Astra only, and `result: "spawned"` or `result: "codex"` counts as success. A Codex success record uses `reply_path: "native"`.
 Host policy sits on top of it. See the Model floor section of the protocol.

package/_shared/advisor/scripts/config/advisor_scripts_constants/model_tier_run_validator_constants.py

@@ -102,3 +102,6 @@ CLI_MISSING_PATH_EXIT_CODE: int = 2
 CLI_INVALID_JSON_EXIT_CODE: int = 2
 CLI_VALIDATION_FAILURE_EXIT_CODE: int = 1
 CLI_SUCCESS_EXIT_CODE: int = 0
+ALL_ADVISOR_REPLY_PATHS: frozenset[str] = frozenset(
+    {"native", "sendmessage", "cli", "codex", "none"}
+)

package/_shared/advisor/scripts/model_tier_run_validator.py

@@ -42,6 +42,7 @@ from __future__ import annotations
 
 import json
 import sys
+from collections.abc import Mapping
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -52,7 +53,21 @@ if _config_directory not in sys.path:
 if _scripts_directory not in sys.path:
     sys.path.insert(0, _scripts_directory)
 
-from advisor_scripts_constants.model_tier_run_validator_constants import (  # noqa: E402
+from advisor_scripts_constants.advisor_route_constants import (
+    ADVISOR_FALLBACK_TIER,
+    ADVISOR_MODEL_TIER,
+    CLI_BIND_SUCCESS_TOKEN,
+    CODEX_BIND_SUCCESS_TOKEN,
+    SPAWN_OUTCOME_KEY,
+    SPAWN_SUCCESS_TOKEN,
+    TIER_KEY,
+)
+from advisor_scripts_constants.astra_advisor_constants import (
+    ASTRA_FALLBACK_KIND_BROKEN,
+    ASTRA_FALLBACK_KIND_DECLINED,
+)
+from advisor_scripts_constants.model_tier_run_validator_constants import (
+    ALL_ADVISOR_REPLY_PATHS,
     ATTEMPT_ORDER_MISMATCH_MESSAGE,
     ATTEMPT_TIER_OUT_OF_SLICE_MESSAGE,
     CANDIDATE_TIERS_MISMATCH_MESSAGE,
@@ -73,16 +88,7 @@ from advisor_scripts_constants.model_tier_run_validator_constants import (  # no
     UNKNOWN_HOST_PROFILE_ERROR,
     UNKNOWN_OWN_TIER_MESSAGE,
 )
-from advisor_scripts_constants.advisor_route_constants import (  # noqa: E402
-    ADVISOR_FALLBACK_TIER,
-    ADVISOR_MODEL_TIER,
-    CODEX_BIND_SUCCESS_TOKEN,
-    CLI_BIND_SUCCESS_TOKEN,
-    SPAWN_OUTCOME_KEY,
-    SPAWN_SUCCESS_TOKEN,
-    TIER_KEY,
-)
-from tier_model_ids import canonical_host_profile, canonical_tier_name  # noqa: E402
+from tier_model_ids import canonical_host_profile, canonical_tier_name
 
 
 @dataclass(frozen=True)
@@ -94,12 +100,157 @@ class ModelTierRun:
     fallback_reason: str | None = None
     is_astra_enabled: bool = False
     host_profile: str = HOST_PROFILE_CLAUDE
+    evidence: dict[str, object] | None = None
 
 
 class ModelTierRunError(ValueError):
     """Raised when a model-tier spawn-walk log violates an invariant."""
 
 
+def _required_evidence_text(
+    fields_by_name: Mapping[str, object], section_name: str, field_name: str
+) -> str:
+    raw_field_text = fields_by_name.get(field_name)
+    if not isinstance(raw_field_text, str) or not raw_field_text.strip():
+        raise ModelTierRunError(
+            f"evidence.{section_name}.{field_name} must be a non-empty string"
+        )
+    return raw_field_text.strip()
+
+
+def _required_evidence_list(
+    fields_by_name: Mapping[str, object], section_name: str, field_name: str
+) -> list[str]:
+    raw_field_entries = fields_by_name.get(field_name)
+    if not isinstance(raw_field_entries, list) or not raw_field_entries:
+        raise ModelTierRunError(
+            f"evidence.{section_name}.{field_name} must be a non-empty list"
+        )
+    if any(
+        not isinstance(each_entry, str) or not each_entry.strip()
+        for each_entry in raw_field_entries
+    ):
+        raise ModelTierRunError(
+            f"evidence.{section_name}.{field_name} must contain non-empty strings"
+        )
+    return [each_entry.strip() for each_entry in raw_field_entries]
+
+
+def _required_evidence_section(
+    sections_by_name: Mapping[str, object], section_name: str
+) -> Mapping[str, object]:
+    raw_section = sections_by_name.get(section_name)
+    if not isinstance(raw_section, Mapping):
+        raise ModelTierRunError(f"evidence.{section_name} must be an object")
+    return raw_section
+
+
+def _validate_reference_evidence(sections_by_name: Mapping[str, object]) -> None:
+    reference = _required_evidence_section(sections_by_name, "reference")
+    _required_evidence_text(reference, "reference", "path")
+    reference_status = _required_evidence_text(reference, "reference", "status")
+    if reference_status not in {"missing", "read"}:
+        raise ModelTierRunError("evidence.reference.status must be missing or read")
+    _required_evidence_text(reference, "reference", "repair_action")
+    _required_evidence_text(reference, "reference", "repair_result")
+
+
+def _validate_fallback_tier(
+    fallback_by_name: Mapping[str, object], run: ModelTierRun
+) -> str | None:
+    raw_selected_tier = fallback_by_name.get("selected_tier")
+    if raw_selected_tier is not None and not isinstance(raw_selected_tier, str):
+        raise ModelTierRunError("evidence.fallback.selected_tier must be a string or null")
+    maybe_selected_tier = (
+        canonical_tier_name(raw_selected_tier)
+        if isinstance(raw_selected_tier, str)
+        else None
+    )
+    maybe_run_selected_tier = (
+        canonical_tier_name(run.selected_tier)
+        if run.selected_tier is not None
+        else None
+    )
+    if maybe_selected_tier != maybe_run_selected_tier:
+        raise ModelTierRunError(
+            "evidence.fallback.selected_tier must match selected_tier"
+        )
+    return maybe_run_selected_tier
+
+
+def _validate_fallback_kind(fallback_by_name: Mapping[str, object]) -> None:
+    raw_fallback_kind = fallback_by_name.get("fallback_kind")
+    if raw_fallback_kind not in {
+        None,
+        ASTRA_FALLBACK_KIND_BROKEN,
+        ASTRA_FALLBACK_KIND_DECLINED,
+    }:
+        raise ModelTierRunError(
+            "evidence.fallback.fallback_kind must be declined, broken, or null"
+        )
+    raw_fallback_reason = fallback_by_name.get("fallback_reason")
+    if raw_fallback_reason is not None and (
+        not isinstance(raw_fallback_reason, str) or not raw_fallback_reason.strip()
+    ):
+        raise ModelTierRunError(
+            "evidence.fallback.fallback_reason must be a non-empty string or null"
+        )
+    if raw_fallback_kind is not None and raw_fallback_reason is None:
+        raise ModelTierRunError(
+            "evidence.fallback.fallback_reason is required for a fallback kind"
+        )
+
+
+def _validate_fallback_reply_path(
+    fallback_by_name: Mapping[str, object],
+    run: ModelTierRun,
+    maybe_run_selected_tier: str | None,
+) -> None:
+    reply_path = _required_evidence_text(fallback_by_name, "fallback", "reply_path")
+    if reply_path not in ALL_ADVISOR_REPLY_PATHS:
+        raise ModelTierRunError(
+            "evidence.fallback.reply_path is not a known advisor path"
+        )
+    if (
+        canonical_host_profile(run.host_profile) == HOST_PROFILE_CODEX
+        and maybe_run_selected_tier == ADVISOR_MODEL_TIER
+        and reply_path != "native"
+    ):
+        raise ModelTierRunError(
+            "Codex Astra success requires the native reply path"
+        )
+
+
+def _validate_fallback_evidence(
+    sections_by_name: Mapping[str, object], run: ModelTierRun
+) -> None:
+    fallback = _required_evidence_section(sections_by_name, "fallback")
+    maybe_run_selected_tier = _validate_fallback_tier(fallback, run)
+    _validate_fallback_kind(fallback)
+    _validate_fallback_reply_path(fallback, run, maybe_run_selected_tier)
+
+
+def _validate_consult_evidence(sections_by_name: Mapping[str, object]) -> None:
+    consult = _required_evidence_section(sections_by_name, "consult")
+    for each_field_name in ("changed_evidence", "validation", "unresolved_risks"):
+        _required_evidence_list(consult, "consult", each_field_name)
+    _required_evidence_text(consult, "consult", "report_back_status")
+
+
+def _validate_advisor_evidence(
+    evidence: object,
+    run: ModelTierRun,
+) -> None:
+    if not isinstance(evidence, Mapping):
+        raise ModelTierRunError("evidence must be an object")
+    raw_schema_version = evidence.get("schema_version")
+    if isinstance(raw_schema_version, bool) or raw_schema_version != 1:
+        raise ModelTierRunError("evidence.schema_version must be 1")
+    _validate_reference_evidence(evidence)
+    _validate_fallback_evidence(evidence, run)
+    _validate_consult_evidence(evidence)
+
+
 def _canonical_tier_list(all_tier_names: list[str]) -> list[str] | None:
     all_canonical_tiers: list[str] = []
     for each_tier_name in all_tier_names:
@@ -149,9 +300,7 @@ def _is_successful_attempt_outcome(
         return False
     if outcome_token == SPAWN_SUCCESS_TOKEN:
         return True
-    if outcome_token == CLI_BIND_SUCCESS_TOKEN:
-        return True
-    return False
+    return outcome_token == CLI_BIND_SUCCESS_TOKEN
 
 
 def validate_model_tier_run(run: ModelTierRun) -> None:
@@ -205,6 +354,8 @@ def validate_model_tier_run(run: ModelTierRun) -> None:
         all_attempted_tiers=all_attempted_tiers,
         all_expected_candidates=all_expected_candidates,
     )
+    if run.evidence is not None:
+        _validate_advisor_evidence(run.evidence, run)
 
 
 def _validate_selected_tier(
@@ -262,6 +413,9 @@ def load_model_tier_run_from_json_path(from_path: Path) -> ModelTierRun:
     raw_host_profile = parsed_payload.get(HOST_PROFILE_JSON_KEY, HOST_PROFILE_CLAUDE)
     if not isinstance(raw_host_profile, str):
         raise TypeError(HOST_PROFILE_MUST_BE_STRING_MESSAGE)
+    raw_evidence = parsed_payload.get("evidence")
+    if raw_evidence is not None and not isinstance(raw_evidence, dict):
+        raise TypeError("evidence must be an object")
     return ModelTierRun(
         own_tier=parsed_payload["own_tier"],
         candidate_tiers=list(parsed_payload["candidate_tiers"]),
@@ -270,6 +424,7 @@ def load_model_tier_run_from_json_path(from_path: Path) -> ModelTierRun:
         fallback_reason=parsed_payload.get("fallback_reason"),
         is_astra_enabled=raw_astra_enabled,
         host_profile=raw_host_profile,
+        evidence=raw_evidence,
     )
 
 

package/_shared/advisor/scripts/tests/test_codex_astra_advisor.py

@@ -220,6 +220,12 @@ def test_bind_runs_probe_then_codex() -> None:
         _two_step_runner(calls),
     )
     assert reply.successful
+    assert reply.selected_tier == "Astra"
+    assert reply.outcome == "codex"
+    assert reply.session_id == "thread-1"
+    assert reply.guidance == "PLAN\ninspect"
+    assert reply.signal == "PLAN"
+    assert reply.fallback_kind is None
     assert calls[1] == astra_advisor.build_codex_arguments("codex")
 
 
@@ -311,6 +317,20 @@ def test_active_docs_use_astra_names() -> None:
         assert all(name not in content for name in legacy_names)
 
 
+def test_team_advisor_source_references_resolve_from_the_package_tree() -> None:
+    package_root = SCRIPTS_ROOT.parents[2]
+    skill_path = package_root / ".agents" / "skills" / "team-advisor" / "SKILL.md"
+    all_reference_targets = (
+        "../../../docs/references/advisor-tool.md",
+        "../../../_shared/advisor/advisor-protocol.md",
+        "../../../_shared/advisor/reference/third-party-bind.md",
+        "../../../_shared/advisor/reference/astra-rung.md",
+        "../../../_shared/advisor/reference/consult-format.md",
+    )
+    for each_target in all_reference_targets:
+        assert (skill_path.parent / each_target).is_file(), each_target
+
+
 def test_astra_docs_name_shared_effort_and_helper() -> None:
     advisor_root = SCRIPTS_ROOT.parent
     rung = (advisor_root / "reference" / "astra-rung.md").read_text(encoding="utf-8")

package/_shared/advisor/scripts/tests/test_model_tier_run_validator.py

@@ -37,6 +37,105 @@ ADVISOR_MODEL_TIER = model_tier_run_validator.ADVISOR_MODEL_TIER
 CODEX_BIND_SUCCESS_TOKEN = model_tier_run_validator.CODEX_BIND_SUCCESS_TOKEN
 
 
+def _native_codex_evidence(
+    *,
+    reply_path: str = "native",
+    reference_status: str = "missing",
+) -> dict[str, object]:
+    return {
+        "schema_version": 1,
+        "reference": {
+            "path": "~/.claude/docs/references/advisor-tool.md",
+            "status": reference_status,
+            "repair_action": "use the projected docs root",
+            "repair_result": "read",
+        },
+        "fallback": {
+            "selected_tier": "Astra",
+            "fallback_kind": None,
+            "fallback_reason": None,
+            "reply_path": reply_path,
+        },
+        "consult": {
+            "changed_evidence": ["native bind returned a reply"],
+            "validation": ["signal and session id read back"],
+            "unresolved_risks": ["optional reference projection"],
+            "report_back_status": "recorded",
+        },
+    }
+
+
+def test_codex_native_bind_and_reply_readback_validate() -> None:
+    run = ModelTierRun(
+        own_tier="Opus",
+        candidate_tiers=[ADVISOR_MODEL_TIER],
+        attempts=[{"tier": ADVISOR_MODEL_TIER, "result": "spawned"}],
+        selected_tier=ADVISOR_MODEL_TIER,
+        host_profile="Codex",
+        evidence=_native_codex_evidence(),
+    )
+
+    assert validate_model_tier_run(run) is None
+
+
+def test_codex_native_success_rejects_non_native_reply_path() -> None:
+    evidence = _native_codex_evidence(reply_path="cli")
+    run = ModelTierRun(
+        own_tier="Opus",
+        candidate_tiers=[ADVISOR_MODEL_TIER],
+        attempts=[{"tier": ADVISOR_MODEL_TIER, "result": "spawned"}],
+        selected_tier=ADVISOR_MODEL_TIER,
+        host_profile="Codex",
+        evidence=evidence,
+    )
+
+    with pytest.raises(ModelTierRunError, match="native reply path"):
+        validate_model_tier_run(run)
+
+
+def test_broken_bind_keeps_fallback_evidence_separate_from_reference_gap() -> None:
+    evidence = _native_codex_evidence()
+    evidence["fallback"] = {
+        "selected_tier": None,
+        "fallback_kind": "broken",
+        "fallback_reason": "native Astra bind failed",
+        "reply_path": "none",
+    }
+    run = ModelTierRun(
+        own_tier="Opus",
+        candidate_tiers=[ADVISOR_MODEL_TIER],
+        attempts=[{"tier": ADVISOR_MODEL_TIER, "result": "unavailable"}],
+        selected_tier=None,
+        fallback_reason="native Astra bind failed",
+        host_profile="Codex",
+        evidence=evidence,
+    )
+
+    assert validate_model_tier_run(run) is None
+
+
+def test_cli_reads_versioned_advisor_evidence(tmp_path: Path) -> None:
+    log_path = tmp_path / "model-tier-run.json"
+    log_path.write_text(
+        json.dumps(
+            {
+                "own_tier": "Opus",
+                "candidate_tiers": [ADVISOR_MODEL_TIER],
+                "attempts": [{"tier": ADVISOR_MODEL_TIER, "result": "spawned"}],
+                "selected_tier": ADVISOR_MODEL_TIER,
+                "host_profile": "Codex",
+                "evidence": _native_codex_evidence(reference_status="read"),
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    assert main([str(log_path)]) == 0
+    loaded_run = load_model_tier_run_from_json_path(from_path=log_path)
+    assert loaded_run.evidence is not None
+    assert loaded_run.evidence["consult"]["report_back_status"] == "recorded"
+
+
 def test_clean_single_spawn_at_top_of_slice_passes() -> None:
     run = ModelTierRun(
         own_tier="Opus",

package/bin/install.agents-home.test.mjs

@@ -34,6 +34,7 @@ const PACKAGE_DIRECTORY = dirname(THIS_DIRECTORY);
 const SHIPPED_SKILL_NAME = 'privacy-hygiene';
 const ELI5_SKILL_NAME = 'eli5';
 const E_CODE_REVIEW_SKILL_NAME = 'e-code-review';
+const TEAM_ADVISOR_SKILL_NAME = 'team-advisor';
 const REFERENCE_DIRECTORY_NAME = 'reference';
 const SHIPPED_AGENT_FILE_NAME = 'AGENTS.md';
 const RETIRED_AGENT_FILE_NAMES = ['clean-coder.md', 'code-quality-agent.md', 'pr-description-writer.md'];
@@ -179,6 +180,15 @@ test('a full install writes skills and agents under .agents and points .claude a
         assert.equal(realpathSync(lookupSkillFile), realpathSync(canonicalSkillFile));
         assert.equal(realpathSync(lookupEli5SkillFile), realpathSync(canonicalEli5SkillFile));
         assertProposalContractInstallation({ skillsInstallDirectory });
+        const projectedAdvisorPaths = [
+            join(skillsInstallDirectory, TEAM_ADVISOR_SKILL_NAME, 'SKILL.md'),
+            join(claudeHome, 'docs', 'references', 'advisor-tool.md'),
+            join(claudeHome, '_shared', 'advisor', 'advisor-protocol.md'),
+            join(agentsInstallDirectory, 'poteto-agent.md'),
+        ];
+        for (const eachPath of projectedAdvisorPaths) {
+            assert.ok(existsSync(eachPath), eachPath);
+        }
         assert.equal(
             readFileSync(lookupAgentFile, 'utf8'),
             readFileSync(canonicalAgentFile, 'utf8'),

package/bin/install.test.mjs

@@ -209,6 +209,20 @@ test('core includeDirectories ships _shared and scripts for advisor protocol and
 });
 
 
+test('team-advisor records fallback repair and consult evidence', () => {
+    const skillPath = new URL('../.agents/skills/team-advisor/SKILL.md', import.meta.url);
+    const skillSource = readFileSync(skillPath, 'utf8');
+    assert.match(skillSource, /Mark `fallback_kind: broken` only when the selected bind or reply path fails/);
+    assert.match(skillSource, /Record the selected tier, fallback reason, and reply path/);
+    assert.match(skillSource, /changed evidence, validation, unresolved risks, and report-back status/);
+    assert.match(skillSource, /reference gap.*bind status separate/);
+    assert.match(skillSource, /selected_tier: Astra.*reply_path: native/);
+    assert.match(skillSource, /model-tier-run\.json/);
+    const advisorReferenceDocumentUrl = new URL('../docs/references/advisor-tool.md', import.meta.url);
+    assert.match(readFileSync(advisorReferenceDocumentUrl, 'utf8'), /"schema_version": 1/);
+});
+
+
 test('CORE_SKILLS ships issue-tracker so the core group installs the skill the SessionStart injector needs', () => {
     assert.ok(
         CORE_SKILLS.includes('issue-tracker'),

package/docs/references/advisor-tool.md

@@ -38,6 +38,38 @@ If your data points one way and the advisor points another: do not silently swit
 
 Work a disagreement in this order: keep the observed evidence in the record, name the conflict plainly, ask the advisor which constraint breaks the tie, then act on the reconciled plan.
 
+## Recovery record
+
+Keep one versioned `evidence` object in the session-controlled `model-tier-run.json` record. A missing optional reference belongs in `reference.status`; it keeps the bind result independent. `fallback_kind: "broken"` identifies a bind or reply failure. On a Codex host, a successful native route records `selected_tier: "Astra"` and `reply_path: "native"`.
+
+```json
+{
+  "evidence": {
+    "schema_version": 1,
+    "reference": {
+      "path": "~/.claude/docs/references/advisor-tool.md",
+      "status": "missing",
+      "repair_action": "use the projected docs root",
+      "repair_result": "read"
+    },
+    "fallback": {
+      "selected_tier": "Astra",
+      "fallback_kind": null,
+      "fallback_reason": null,
+      "reply_path": "native"
+    },
+    "consult": {
+      "changed_evidence": ["native bind returned a reply"],
+      "validation": ["signal and session id read back"],
+      "unresolved_risks": ["optional reference projection"],
+      "report_back_status": "recorded"
+    }
+  }
+}
+```
+
+The repair fields preserve the reference-path result. The fallback fields preserve route selection and bind or reply failures. The consult fields preserve first, recovery, and completion readback.
+
 ## Escalation shapes
 
 Four shapes cover how a harder task gets more strength behind it. Route to the one that matches the work, not by default to the advisor.

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

@@ -6,7 +6,7 @@
 
 | Doc | Holds |
 |---|---|
-| `skills/team-advisor/SKILL.md` | Sole-consumer bind wiring and constraints |
+| `.agents/skills/team-advisor/SKILL.md` | Sole-consumer bind wiring and constraints |
 | `advisor-tool.md` | Consult timing, hard rule, how to treat advice |
 | `~/.claude/_shared/advisor/advisor-protocol.md` | Session identity, host bind, floor, lifecycle |
 | `agents/session-advisor.md` | ENDORSE / CORRECTION / PLAN / STOP |

package/hooks/validators/README.md

@@ -37,7 +37,6 @@ The checks live in `python_style_checks.py`. Shared source-line splitting, funct
 | `type_safety_checks.py` | Missing type hints and Any usage checks |
 | `useless_test_checks.py` | Useless-test detection |
 | `validator_base.py` | Shared validator dataclasses, source read, and parse |
-| `validator_defaults.py` | Shared constants for the validators package |
 
 ## Checks Implemented
 

package/hooks/validators/test_files/EXECUTIVE_SUMMARY.md

@@ -23,7 +23,7 @@ class RegularComponent extends Component { }      // Line 4 - CAUGHT ✓
 class OptimizedComponent extends PureComponent { } // Line 9 - MISSED ✗
 ```
 
-**Impact:** HIGH - PureComponent is commonly used for performance optimization. Developers will bypass the check by using PureComponent instead of Component.
+**Impact:** HIGH - PureComponent is commonly used for performance optimization. Developers may bypass the check by selecting PureComponent where Component is expected.
 
 **Fix:** Add to regex pattern:
 ```python
@@ -149,7 +149,6 @@ Consider for future iteration if multi-class files become common.
 
 All test files in `test_files/` directory:
 - `01-16_*.tsx` - Individual test cases
-- `VALIDATION_REPORT.md` - Detailed test results
 - `EXECUTIVE_SUMMARY.md` - This file
 
 Run all tests:

package/package.json

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

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/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/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%

package/hooks/validators/VALIDATION_REPORT.md

@@ -1,287 +0,0 @@
-# Test Safety Checks Validator - Comprehensive Validation Report
-
-## Executive Summary
-
-**Critical Gaps Found: 2**
-**Minor Issues: 1**
-**Tests Passed: 14/17**
-
----
-
-## Check 1: No Skip Decorators
-
-### Test Results
-
-| Test Case | Expected | Result | Status |
-|-----------|----------|--------|--------|
-| `@skip` | CAUGHT | CAUGHT | PASS |
-| `@pytest.mark.skipif(...)` | CAUGHT | CAUGHT | PASS |
-| `@unittest.skipIf(...)` | CAUGHT | CAUGHT | PASS |
-| `@skip()` with parentheses | CAUGHT | CAUGHT | PASS |
-| `@pytest.mark.xfail` | ALLOWED | ALLOWED | PASS |
-| `@skip_on_windows` custom | ALLOWED | ALLOWED | PASS |
-| `@Skip` (capital S) | CAUGHT | **ALLOWED** | **FAIL** |
-| `@unittest.skipUnless(...)` | CAUGHT | CAUGHT | PASS |
-| `@pytest.mark.skip` (no args) | CAUGHT | CAUGHT | PASS |
-
-### GAP #1: Case-Sensitive Decorator Matching
-
-**Severity: MEDIUM**
-
-**Issue:** The validator uses case-sensitive matching, so `@Skip` (capital S) is NOT caught.
-
-**Current Code (lines 16-22):**
-```python
-SKIP_DECORATOR_NAMES = frozenset([
-    "skip",
-    "skipif",
-    "skipunless",
-    "skipIf",
-    "skipUnless",
-])
-```
-
-**Problem:** This misses decorators with different capitalization like `@Skip`, `@SkipIf`, `@SKIP`, etc.
-
-**Recommended Fix:**
-```python
-def _get_decorator_name(decorator: ast.expr) -> str:
-    """Extract the name from a decorator node (lowercase for comparison)."""
-    # ... existing logic ...
-    return name.lower()  # Convert to lowercase for case-insensitive matching
-```
-
-Then update the frozenset to all lowercase:
-```python
-SKIP_DECORATOR_NAMES = frozenset([
-    "skip",
-    "skipif",
-    "skipunless",
-])
-```
-
-**Impact:** Currently allows `@Skip`, `@SkipIf`, `@SkipUnless` to slip through.
-
----
-
-## Check 2: DEBUG Guard in Management Commands
-
-### Test Results
-
-| Test Case | Expected | Result | Status |
-|-----------|----------|--------|--------|
-| No DEBUG check | CAUGHT | CAUGHT | PASS |
-| `if not settings.DEBUG: raise` | ALLOWED | ALLOWED | PASS |
-| `if not settings.DEBUG: return` | ALLOWED | ALLOWED | PASS |
-| Using imported `DEBUG` variable | CAUGHT | CAUGHT | PASS |
-| DEBUG check in helper function | CAUGHT | CAUGHT | PASS |
-| DEBUG check after 5 statements | CAUGHT | CAUGHT | PASS |
-| `if settings.DEBUG: ... else: raise` | ALLOWED | **CAUGHT** | **FAIL** |
-| `if not settings.DEBUG and X:` | DEBATABLE | CAUGHT | WARN |
-| File not in `management/commands/` | IGNORED | IGNORED | PASS |
-
-### GAP #2: Positive DEBUG Check Pattern Rejected
-
-**Severity: HIGH**
-
-**Issue:** The validator incorrectly rejects the pattern `if settings.DEBUG: ... else: raise`.
-
-**Test File:** `cmd_07_positive_debug_check.py`
-```python
-def handle(self, *args, **options):
-    if settings.DEBUG:
-        print("Running in DEBUG mode")
-    else:
-        raise CommandError("This command can only be run in DEBUG mode")
-```
-
-**Expected:** ALLOWED (this is a valid DEBUG guard)
-**Actual:** CAUGHT (flagged as violation)
-
-**Root Cause (lines 186-187):**
-```python
-if _is_debug_check(test) and stmt.orelse:
-    return False  # This returns False when it should return True!
-```
-
-**The Logic Flaw:**
-- Line 186: Detects `if settings.DEBUG:` and checks if there's an `else` clause
-- Line 187: Returns `False` (no DEBUG guard found)
-- **BUG:** This should return `True` because the pattern IS a valid guard!
-
-**Recommended Fix:**
-```python
-def _has_debug_guard(func: ast.FunctionDef) -> bool:
-    """Check if a function has a settings.DEBUG guard at the start."""
-    if not func.body:
-        return False
-
-    for stmt in func.body[:5]:
-        if isinstance(stmt, ast.If):
-            test = stmt.test
-
-            # Pattern 1: if not settings.DEBUG: raise/return
-            if isinstance(test, ast.UnaryOp) and isinstance(test.op, ast.Not):
-                if _is_debug_check(test.operand):
-                    return True
-
-            # Pattern 2: if settings.DEBUG: ... else: raise/return
-            if _is_debug_check(test):
-                if stmt.orelse:
-                    # Check if else clause has raise/return
-                    if _has_early_exit(stmt.orelse):
-                        return True
-                # if settings.DEBUG: with no else is also valid
-                return True
-
-    return False
-
-
-def _has_early_exit(statements: List[ast.stmt]) -> bool:
-    """Check if statements contain raise or return."""
-    for stmt in statements:
-        if isinstance(stmt, (ast.Raise, ast.Return)):
-            return True
-        # Check nested if/else
-        if isinstance(stmt, ast.If):
-            if _has_early_exit(stmt.body) or (stmt.orelse and _has_early_exit(stmt.orelse)):
-                return True
-    return False
-```
-
-**Impact:** Currently REJECTS valid DEBUG guard patterns, forcing developers to use only negative checks.
-
-### MINOR ISSUE: Complex Boolean Expressions
-
-**Severity: LOW**
-
-**Issue:** The validator rejects `if not settings.DEBUG and other_condition:`.
-
-**Test File:** `cmd_08_debug_with_and.py`
-```python
-if not settings.DEBUG and True:
-    raise CommandError("This command can only be run in DEBUG mode")
-```
-
-**Expected:** DEBATABLE (could be allowed if DEBUG is the primary condition)
-**Actual:** CAUGHT (flagged as violation)
-
-**Analysis:**
-- Current code only checks for simple `UnaryOp(Not)` with `settings.DEBUG`
-- Doesn't handle `BoolOp` (and/or) expressions
-- This is arguably correct behavior - keeps the check simple and strict
-
-**Recommendation:** Document this limitation. Developers should use:
-```python
-if not settings.DEBUG:
-    raise CommandError("...")
-# Then check other conditions separately
-```
-
----
-
-## Additional Edge Cases Tested
-
-### Nested Directory Structure
-- File in `management/commands/subdir/command.py` - NOT tested
-- **Recommendation:** Add test case to verify path matching works with subdirectories
-
-### File Encoding Issues
-- Files with syntax errors - Handled gracefully (returns empty violations)
-- Files that don't exist - Handled with error message
-
-### Multiple Commands in One File
-- NOT tested
-- **Recommendation:** Add test case with multiple Command classes in one file
-
----
-
-## Recommended Priority Fixes
-
-1. **HIGH PRIORITY:** Fix GAP #2 (positive DEBUG check pattern)
-   - Current behavior rejects valid code
-   - Breaking change for developers using this pattern
-
-2. **MEDIUM PRIORITY:** Fix GAP #1 (case-sensitive skip decorators)
-   - Low probability but easy to fix
-   - Prevents trivial evasion
-
-3. **LOW PRIORITY:** Add test for nested management commands
-   - Verify path matching works with subdirectories
-
----
-
-## Test Coverage Summary
-
-**Skip Decorators:**
-- Simple decorators: TESTED
-- Attribute decorators: TESTED
-- Called decorators: TESTED
-- Case variations: **GAP FOUND**
-- Custom decorators: TESTED (correctly allowed)
-
-**DEBUG Guards:**
-- No check: TESTED
-- Negative check (`if not`): TESTED
-- Positive check (`if ... else`): **GAP FOUND**
-- Imported DEBUG: TESTED (correctly rejected)
-- Helper function: TESTED (correctly rejected)
-- Late check (>5 statements): TESTED (correctly rejected)
-- Path matching: TESTED
-- Complex boolean: TESTED (debatable behavior)
-
----
-
-## Files Created for Testing
-
-### Skip Decorators (9 files)
-```
-test_files/skip_decorators/
-├── test_01_simple_skip.py
-├── test_02_pytest_skipif.py
-├── test_03_unittest_skipIf.py
-├── test_04_skip_with_parens.py
-├── test_05_xfail.py
-├── test_06_custom_skip.py
-├── test_07_capital_Skip.py (GAP)
-├── test_08_skipUnless.py
-└── test_09_pytest_mark_skip_simple.py
-```
-
-### Management Commands (9 files)
-```
-test_files/management/commands/
-├── cmd_01_no_debug_check.py
-├── cmd_02_proper_debug_check.py
-├── cmd_03_debug_check_with_return.py
-├── cmd_04_imported_DEBUG.py
-├── cmd_05_debug_check_in_helper.py
-├── cmd_06_debug_check_late.py
-├── cmd_07_positive_debug_check.py (GAP)
-├── cmd_08_debug_with_and.py
-test_files/
-└── not_management_command.py
-```
-
----
-
-## Conclusion
-
-The validator is **mostly effective** but has **2 critical gaps**:
-
-1. **Case-sensitive decorator matching** - Easy fix, low impact
-2. **Positive DEBUG check rejection** - HIGH PRIORITY, rejects valid code
-
-The implementation correctly handles:
-- Most skip decorator patterns
-- Simple DEBUG guard patterns
-- Path filtering for management commands
-- Graceful error handling
-
-**Overall Assessment: 82% effective (14/17 test cases passed)**
-
-**Action Required:**
-1. Fix GAP #2 immediately (breaking valid code)
-2. Fix GAP #1 for completeness
-3. Add test for nested management command directories
-4. Document the complex boolean limitation

package/hooks/validators/validator_defaults.py

@@ -1,5 +0,0 @@
-"""Shared constants for the validators package."""
-
-# pragma: no-tdd-gate
-
-DEFAULT_BASE_BRANCH_WHEN_UNKNOWN = "main"