claude-dev-env 8.2.0 → 8.4.0

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

@@ -12,6 +12,7 @@ import {
     mkdirSync,
     mkdtempSync,
     readFileSync,
+    readdirSync,
     realpathSync,
     rmSync,
     writeFileSync,
@@ -33,39 +34,10 @@ 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 = 'clean-coder.md';
-const SHIPPED_AGENT_FILE_NAMES = [
-    SHIPPED_AGENT_FILE_NAME,
-    'code-quality-agent.md',
-    'pr-description-writer.md',
-];
-const CLEAN_CODER_POLICY_REFERENCES = [
-    [
-        '<managed-root>/docs/CODE_RULES.md',
-        'packages/claude-dev-env/docs/CODE_RULES.md',
-    ],
-    [
-        '<managed-root>/hooks/blocking/code_rules_enforcer.py',
-        'packages/claude-dev-env/hooks/blocking/code_rules_enforcer.py',
-    ],
-    [
-        '<managed-root>/rules/code-standards.md',
-        'packages/claude-dev-env/rules/code-standards.md',
-    ],
-    [
-        '<managed-root>/rules/windows-filesystem-safe.md',
-        'packages/claude-dev-env/rules/windows-filesystem-safe.md',
-    ],
-    [
-        '<managed-root>/rules/gh-cli-conventions.md',
-        'packages/claude-dev-env/rules/gh-cli-conventions.md',
-    ],
-    [
-        '<managed-root>/rules/plain-illustrative-docstrings.md',
-        'packages/claude-dev-env/rules/plain-illustrative-docstrings.md',
-    ],
-];
+const SHIPPED_AGENT_FILE_NAME = 'AGENTS.md';
+const RETIRED_AGENT_FILE_NAMES = ['clean-coder.md', 'code-quality-agent.md', 'pr-description-writer.md'];
 const PERSONAL_SKILL_NAME = 'my-notes';
 const PREFLIGHT_PROPOSAL_FILE_NAME = 'preflight-proposal.md';
 
@@ -116,37 +88,48 @@ function assertProposalContractInstallation(installationPaths) {
     assert.equal(readFileSync(installedContractPath, 'utf8'), readFileSync(sourceContractPath, 'utf8'));
 }
 
-/**
- * @param {string} agentFilePath
- * @param {string} layoutName
- * @param {string} managedRoot
- * @returns {string[]}
- */
-function cleanCoderPolicyReferenceProblems(agentFilePath, layoutName, managedRoot) {
-    const agentBody = readFileSync(agentFilePath, 'utf8');
-    const missingReferences = [];
-    for (const [installedReference, sourceReference] of CLEAN_CODER_POLICY_REFERENCES) {
-        const eachReference = layoutName === 'source'
-            ? sourceReference
-            : installedReference;
-        const eachTargetPath = sourceReference.replace('packages/claude-dev-env/', '');
-        if (!agentBody.includes(eachReference)) {
-            missingReferences.push(eachReference + ' is absent');
-        }
-        const resolvedPath = layoutName === 'source'
-            ? join(PACKAGE_DIRECTORY, eachTargetPath)
-            : join(managedRoot, eachTargetPath);
-        if (!existsSync(resolvedPath)) {
-            missingReferences.push(layoutName + ': ' + resolvedPath);
-        }
-    }
-    return missingReferences.map((reference) => layoutName + ': ' + reference);
-}
 
 test('CONTENT_DIRECTORIES omits agents because that tree installs to the agents home', () => {
     assert.equal(CONTENT_DIRECTORIES.includes(MANAGED_AGENTS_DIRECTORY_NAME), false);
 });
 
+test('full install archives recorded retired agents and preserves third-party agents', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agent-retirement-'));
+    try {
+        runInstaller(homeDirectory, []);
+        const agentsDirectory = join(homeDirectory, '.agents', 'agents');
+        const retiredPath = join(agentsDirectory, 'clean-coder.md');
+        const pluginPath = join(agentsDirectory, 'poteto-agent.md');
+        const activePath = join(agentsDirectory, 'AGENTS.md');
+        const sourcePluginPath = join(PACKAGE_DIRECTORY, '.agents', 'agents', 'poteto-agent.md');
+        assert.equal(readFileSync(pluginPath, 'utf8'), readFileSync(sourcePluginPath, 'utf8'));
+        writeFileSync(retiredPath, 'recover this retired definition\n');
+        writeFileSync(pluginPath, 'preserve this plugin definition\n');
+        const manifestPath = join(homeDirectory, '.claude', '.claude-dev-env-manifest.json');
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        manifest.files.push(retiredPath);
+        manifest.files.push(activePath);
+        writeFileSync(manifestPath, JSON.stringify(manifest));
+
+        runInstaller(homeDirectory, []);
+
+        assert.equal(existsSync(retiredPath), false);
+        assert.ok(existsSync(activePath));
+        const backupRoot = join(homeDirectory, '.claude', '.claude-dev-env-pruned');
+        const backupNames = readdirSync(backupRoot, { recursive: true });
+        const retiredBackup = backupNames.find(name => name.endsWith('clean-coder.md'));
+        assert.ok(retiredBackup);
+        assert.equal(readFileSync(join(backupRoot, retiredBackup), 'utf8'), 'recover this retired definition\n');
+        assert.equal(readFileSync(pluginPath, 'utf8'), 'preserve this plugin definition\n');
+        const updatedManifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        assert.equal(updatedManifest.files.includes(retiredPath), false);
+        runInstaller(homeDirectory, []);
+        assert.equal(readFileSync(pluginPath, 'utf8'), 'preserve this plugin definition\n');
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
 test('a full install writes skills and agents under .agents and points .claude at them', () => {
     const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agents-home-'));
     const claudeHome = join(homeDirectory, '.claude');
@@ -197,22 +180,19 @@ 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'),
         );
-        const sourceAgentFile = join(
-            resolvePackageManagedDirectory(
-                PACKAGE_DIRECTORY,
-                MANAGED_AGENTS_DIRECTORY_NAME,
-            ),
-            SHIPPED_AGENT_FILE_NAME,
-        );
-        const brokenPolicyReferences = [
-            ...cleanCoderPolicyReferenceProblems(sourceAgentFile, 'source', claudeHome),
-            ...cleanCoderPolicyReferenceProblems(canonicalAgentFile, 'installed', claudeHome),
-        ];
-        assert.deepEqual(brokenPolicyReferences, [], 'Clean Coder has broken policy references');
         assert.equal(realpathSync(lookupAgentFile), realpathSync(canonicalAgentFile));
         assert.equal(
             lstatSync(skillsInstallDirectory).isSymbolicLink(),
@@ -229,7 +209,7 @@ test('a full install writes skills and agents under .agents and points .claude a
     }
 });
 
-test('real installs place the Clean Coder in each active agents home', () => {
+test('installs omit retired agents in each active agents home', () => {
     const runRoot = mkdtempSync(join(tmpdir(), 'cdev-active-roots-'));
     const homeDirectory = join(runRoot, 'home');
     const configRoot = join(runRoot, 'config-profile');
@@ -283,7 +263,7 @@ test('real installs place the Clean Coder in each active agents home', () => {
                     ...eachInstallCase.environment,
                 },
             );
-            for (const eachAgentFileName of SHIPPED_AGENT_FILE_NAMES) {
+            for (const eachAgentFileName of RETIRED_AGENT_FILE_NAMES) {
                 const installedAgentPath = join(
                     eachInstallCase.agentsHome,
                     MANAGED_AGENTS_DIRECTORY_NAME,
@@ -291,30 +271,10 @@ test('real installs place the Clean Coder in each active agents home', () => {
                 );
                 assert.equal(
                     existsSync(installedAgentPath),
-                    true,
-                    `${eachInstallCase.name}: agent is under the active agents home`,
+                    false,
+                    `${eachInstallCase.name}: retired agent is absent`,
                 );
-                const installedAgentText = readFileSync(installedAgentPath, 'utf8');
-                assert.match(installedAgentText, /active managed root/i);
-                assert.match(installedAgentText, /active agents home/i);
-                assert.match(installedAgentText, /<managed-root>\//);
-                assert.match(installedAgentText, /<agents-home>\//);
             }
-            const installedCleanCoderPath = join(
-                eachInstallCase.agentsHome,
-                MANAGED_AGENTS_DIRECTORY_NAME,
-                SHIPPED_AGENT_FILE_NAME,
-            );
-            const policyReferenceProblems = cleanCoderPolicyReferenceProblems(
-                installedCleanCoderPath,
-                'installed',
-                eachInstallCase.managedRoot,
-            );
-            assert.deepEqual(
-                policyReferenceProblems,
-                [],
-                `${eachInstallCase.name}: Clean Coder has broken policy references`,
-            );
             assert.equal(
                 isDirectoryPointerTo(
                     join(eachInstallCase.managedRoot, MANAGED_AGENTS_DIRECTORY_NAME),

package/bin/install.mjs

@@ -1135,6 +1135,7 @@ function renameCaseOnlyMatchToShippedName(destinationFilePath, entryNamesByDirec
 
 export function copyTree(sourceBase, destBase, options = {}) {
     const excludedFileNames = new Set(options.excludeFileNames ?? []);
+    const preservedFileNames = new Set(options.preserveExistingFileNames ?? []);
     const files = collectFiles(sourceBase).filter(
         sourceFile => !excludedFileNames.has(basename(sourceFile)),
     );
@@ -1144,6 +1145,10 @@ export function copyTree(sourceBase, destBase, options = {}) {
         const relativePath = relative(sourceBase, sourceFile);
         const destFile = join(destBase, relativePath);
         mkdirSync(dirname(destFile), { recursive: true });
+        if (preservedFileNames.has(basename(sourceFile)) && existsSync(destFile)) {
+            stats.paths.push(destFile);
+            continue;
+        }
         const existed = existsSync(destFile);
         renameCaseOnlyMatchToShippedName(destFile, entryNamesByDirectory, options);
         copyFileSync(sourceFile, destFile);
@@ -1223,6 +1228,8 @@ export const POST_FOLDED_HOOK_RELATIVE_PATHS = new Set([
 ]);
 
 export const RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS = new Set([
+    'observability/test_failure_recorder.py',
+    'advisory/msys_path_conversion_advisor.py',
     'session/untracked_repo_detector.py',
     'session/gh_pr_author_session_cleanup.py',
     'observability/pr_description_writer_spawn_tracker.py',
@@ -2326,29 +2333,6 @@ function pruneRetiredSkills(installedSkillNames, priorManifestSkills) {
     return movedDirectoryCount;
 }
 
-/**
- * Move every file a prior install wrote under a managed root that this run leaves
- * unwritten into the run's backup root, one call per root.
- *
- * `copyTree` adds and overwrites but never removes, so every managed root carries
- * the same drift the skills root does. One call per root hands the containment
- * guard and the emptied-parent walk the root that owns each file, and each root's
- * content lands under `<backupRoot>/<root-name>/<relative>`, so the recovery point
- * mirrors ~/.claude.
- *
- * Nothing moves unless a prior install recorded it. A user-authored file, a
- * runtime artifact, and a recorded path under no managed root — ~/.claude/CLAUDE.md,
- * settings.json, the manifest itself, and ~/.mypy.ini outside the home — all sit
- * outside every root's diff and stay where they are. ~/.claude/_shared and
- * ~/.claude/skills/_shared are distinct absolute paths, so the `_shared` root call
- * and the skills root call each see their own files and neither sees the other's.
- *
- * @param {string[]|null} priorInstalledFiles Files the prior manifest recorded, or null when unknown.
- * @param {string[]} currentInstalledFiles Every file this run copied.
- * @param {string} backupRoot The run's timestamped backup directory.
- * @returns {{prunedCount: number, skillsPrunedCount: number, failedPaths: string[]}}
- *   The summed count, the skills root's own count, and every path whose move failed.
- */
 function pruneStaleFilesAcrossManagedRoots(priorInstalledFiles, currentInstalledFiles, backupRoot) {
     let prunedCount = 0;
     let skillsPrunedCount = 0;
@@ -2366,6 +2350,27 @@ function pruneStaleFilesAcrossManagedRoots(priorInstalledFiles, currentInstalled
             skillsPrunedCount = rootOutcome.prunedCount;
         }
     }
+    for (const rootName of [MANAGED_AGENTS_DIRECTORY_NAME, MANAGED_SKILLS_DIRECTORY_NAME]) {
+        const lookupRoot = join(CLAUDE_HOME, rootName);
+        const canonicalRoot = join(AGENTS_HOME, rootName);
+        const canonicalCurrentFiles = currentInstalledFiles.map(filePath =>
+            isInsideDirectory(filePath, lookupRoot)
+                ? join(canonicalRoot, relative(lookupRoot, filePath))
+                : filePath,
+        );
+        const rootOutcome = pruneStaleInstalledFiles(
+            priorInstalledFiles,
+            canonicalCurrentFiles,
+            canonicalRoot,
+            join(backupRoot, 'agents-home', rootName),
+            { managedHomeDirectory: AGENTS_HOME },
+        );
+        prunedCount += rootOutcome.prunedCount;
+        failedPaths.push(...rootOutcome.failedPaths);
+        if (rootName === MANAGED_SKILLS_DIRECTORY_NAME) {
+            skillsPrunedCount += rootOutcome.prunedCount;
+        }
+    }
     return { prunedCount, skillsPrunedCount, failedPaths };
 }
 
@@ -2655,7 +2660,9 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
             );
             if (!existsSync(agentsSource)) continue;
             const agentsDestination = INSTALL_ROOT_RESOLUTION.agentsLookupDirectory;
-            const stats = copyTree(agentsSource, agentsDestination);
+            const stats = copyTree(agentsSource, agentsDestination, {
+                preserveExistingFileNames: ['poteto-agent.md'],
+            });
             if (!summary[MANAGED_AGENTS_DIRECTORY_NAME]) {
                 summary[MANAGED_AGENTS_DIRECTORY_NAME] = stats;
             } else {