claude-dev-env 8.10.0 → 8.11.0

package/_shared/pr-loop/scripts/code_rules_gate_parts/staged_test_regression.py

@@ -385,11 +385,13 @@ def _first_nonzero(all_exit_codes: Iterable[int]) -> int:
     return 0
 
 
-def _add_baseline_worktree(repository_root: Path, baseline_worktree: Path) -> bool:
-    """Attach a detached-HEAD checkout at *baseline_worktree*; True when git created it."""
+def _add_baseline_worktree(
+    repository_root: Path, baseline_worktree: Path, revision: str = GIT_HEAD_REVISION
+) -> bool:
+    """Attach a detached checkout of *revision* at *baseline_worktree*; True when git created it."""
     worktree_added = _run_git(
         repository_root,
-        (*ALL_GIT_WORKTREE_ADD_DETACH_ARGS, str(baseline_worktree), GIT_HEAD_REVISION),
+        (*ALL_GIT_WORKTREE_ADD_DETACH_ARGS, str(baseline_worktree), revision),
     )
     return worktree_added.returncode == 0
 
@@ -515,6 +517,86 @@ def run_grouped_tests_with_regression_gate(
     return first_failing_exit_code
 
 
+def _overlay_files_into_worktree(
+    all_overlay_paths: list[Path], repository_root: Path, baseline_worktree: Path
+) -> None:
+    """Copy each working-tree file onto the same relative path inside the worktree."""
+    for each_path in all_overlay_paths:
+        worktree_path = _path_under_baseline_worktree(
+            each_path, repository_root, baseline_worktree
+        )
+        worktree_path.parent.mkdir(parents=True, exist_ok=True)
+        worktree_path.write_bytes(each_path.read_bytes())
+
+
+def _revision_outcomes(
+    all_tests_by_root: dict[Path, list[Path]],
+    repository_root: Path,
+    revision: str,
+    all_overlay_paths: list[Path],
+    junit_root: Path,
+) -> dict[Path, GroupOutcome] | None:
+    """Run every group in a worktree of *revision* with the overlay files copied in."""
+    with tempfile.TemporaryDirectory(
+        prefix=REGRESSION_BASELINE_WORKTREE_TEMP_DIRECTORY_PREFIX,
+        ignore_cleanup_errors=True,
+    ) as baseline_parent_text:
+        baseline_worktree = (
+            Path(baseline_parent_text) / REGRESSION_BASELINE_WORKTREE_DIRECTORY_NAME
+        )
+        if not _add_baseline_worktree(repository_root, baseline_worktree, revision):
+            return None
+        try:
+            _overlay_files_into_worktree(
+                all_overlay_paths, repository_root, baseline_worktree
+            )
+            return _baseline_outcomes_for_failing_groups(
+                repository_root, all_tests_by_root, junit_root, baseline_worktree
+            )
+        finally:
+            _remove_baseline_worktree(repository_root, baseline_worktree)
+
+
+def working_tree_and_revision_outcomes(
+    all_tests_by_root: dict[Path, list[Path]],
+    repository_root: Path,
+    revision: str,
+    all_overlay_paths: list[Path],
+) -> tuple[dict[Path, GroupOutcome], dict[Path, GroupOutcome] | None]:
+    """Run the test groups on the working tree, then on *revision* with overlays copied in.
+
+    ::
+
+        working tree: pkg/test_calc.py passes            -> exit 0
+        revision:     base code + head pkg/test_calc.py  -> fails, the test proves the fix
+
+    The revision run reuses the baseline worktree and its import isolation, so
+    a run that read working-tree code reports no failures.
+
+    Args:
+        all_tests_by_root: Test files grouped by owning pytest-config root.
+        repository_root: The repository the test files belong to.
+        revision: The git revision the second run checks out.
+        all_overlay_paths: Working-tree files copied into the revision checkout
+            before it runs, such as the test files a change adds or edits.
+
+    Returns:
+        The working-tree outcomes, and the revision outcomes keyed by the same
+        group roots, or None when git could not create the revision worktree.
+    """
+    with tempfile.TemporaryDirectory(
+        prefix=REGRESSION_JUNIT_TEMP_DIRECTORY_PREFIX
+    ) as junit_root_text:
+        junit_root = Path(junit_root_text)
+        working_tree_outcomes = _run_staged_groups(
+            all_tests_by_root, repository_root, junit_root
+        )
+        revision_outcomes = _revision_outcomes(
+            all_tests_by_root, repository_root, revision, all_overlay_paths, junit_root
+        )
+    return working_tree_outcomes, revision_outcomes
+
+
 def run_staged_test_files(repository_root: Path) -> int:
     """Discover the staged test files and run them under the regression gate.
 

package/_shared/pr-loop/scripts/code_rules_gate_parts/tests/test_staged_test_regression.py

@@ -307,3 +307,37 @@ def test_run_staged_test_files_passes_when_config_less_packages_share_a_module_n
     _stage_package_owning_a_bare_config(repository_root, "beta_package", "beta")
 
     assert staged_test_regression.run_staged_test_files(repository_root) == 0
+
+
+def test_a_revision_run_executes_an_overlaid_test_against_the_older_code(
+    tmp_path: Path,
+) -> None:
+    repository_root = repository_with_root_pytest_config(tmp_path)
+    write_and_stage(repository_root, "pkg_a/calc.py", "VALUE = 'old'\n")
+    run_git(repository_root, "commit", "--no-verify", "-m", "old value")
+    base_revision = (
+        run_git(repository_root, "rev-parse", "HEAD").stdout.decode().strip()
+    )
+    write_and_stage(repository_root, "pkg_a/calc.py", "VALUE = 'new'\n")
+    test_path = write_and_stage(
+        repository_root,
+        "pkg_a/test_calc.py",
+        "from calc import VALUE\n\n\ndef test_value_is_new() -> None:\n"
+        "    assert VALUE == 'new'\n",
+    )
+    run_git(repository_root, "commit", "--no-verify", "-m", "new value")
+
+    working_tree_outcomes, revision_outcomes = (
+        staged_test_regression.working_tree_and_revision_outcomes(
+            {repository_root.resolve(): [test_path]},
+            repository_root,
+            base_revision,
+            [test_path],
+        )
+    )
+
+    assert [each.exit_code for each in working_tree_outcomes.values()] == [0]
+    assert revision_outcomes is not None
+    assert [
+        len(each.failing_identities) for each in revision_outcomes.values()
+    ] == [1]

package/_shared/pr-loop/scripts/fix_pr_test_proof.py

@@ -0,0 +1,132 @@
+"""Require a fix pull request to carry a test that fails on its base and passes on its head.
+
+::
+
+    title "docs: ..."                               -> pass, nothing to prove
+    title "fix: ..." changing only docs or .github  -> pass, nothing to prove
+    title "fix: ..." with no changed Python test    -> fail
+    changed test passes on head, fails on base      -> pass
+    changed test passes on both                     -> fail
+
+The base run reuses the regression gate's detached worktree: the changed test
+files are copied onto the base checkout, which runs them with import isolation.
+Python tests only.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from code_rules_gate_parts import staged_test_regression, staged_test_running
+from code_rules_gate_parts.git_file_sets import paths_from_git_diff
+from code_rules_gate_parts.wrapper_plumb_check import is_test_path
+from pr_loop_shared_constants.fix_pr_test_proof_constants import (
+    ALL_PRODUCTION_CODE_SUFFIXES,
+    CI_CONFIG_DIRECTORY_NAME,
+    FAILED_EXIT_CODE,
+    FIX_TITLE_PATTERN,
+    HEAD_FAILURE_MESSAGE,
+    NO_BASE_FAILURE_MESSAGE,
+    NO_CHANGED_TEST_MESSAGE,
+    NO_PRODUCTION_CHANGE_MESSAGE,
+    NOT_A_FIX_MESSAGE,
+    PASSED_EXIT_CODE,
+    PROVEN_MESSAGE,
+    WORKTREE_FAILED_MESSAGE,
+)
+
+
+def _parse_arguments(all_arguments: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog="fix_pr_test_proof")
+    parser.add_argument("--title", required=True)
+    parser.add_argument("--base", dest="base_revision", required=True)
+    parser.add_argument("--repository-root", default=".")
+    return parser.parse_args(all_arguments)
+
+
+def is_production_code_path(file_path: Path, repository_root: Path) -> bool:
+    """Return whether a changed path is production code a fix must prove.
+
+    Args:
+        file_path: An absolute changed path.
+        repository_root: The repository the path belongs to.
+
+    Returns:
+        True for a code file outside the test patterns and outside ``.github``.
+    """
+    relative_path = file_path.relative_to(repository_root)
+    if relative_path.parts and relative_path.parts[0] == CI_CONFIG_DIRECTORY_NAME:
+        return False
+    if file_path.suffix not in ALL_PRODUCTION_CODE_SUFFIXES:
+        return False
+    return not is_test_path(relative_path.as_posix())
+
+
+def _changed_python_tests(all_changed_paths: list[Path]) -> list[Path]:
+    return [
+        each_path
+        for each_path in all_changed_paths
+        if each_path.suffix == ".py"
+        and is_test_path(each_path.as_posix())
+        and each_path.is_file()
+    ]
+
+
+def _proof_exit_code(
+    all_changed_tests: list[Path], repository_root: Path, base_revision: str
+) -> int:
+    all_targets = staged_test_running._pytest_target_paths(all_changed_tests)
+    all_tests_by_root = staged_test_running._group_staged_tests_by_root(
+        all_targets, repository_root
+    )
+    head_outcomes, base_outcomes = (
+        staged_test_regression.working_tree_and_revision_outcomes(
+            all_tests_by_root, repository_root, base_revision, all_changed_tests
+        )
+    )
+    for each_group_root, each_outcome in sorted(head_outcomes.items()):
+        if each_outcome.exit_code != 0:
+            sys.stderr.write(HEAD_FAILURE_MESSAGE.format(group_root=each_group_root) + "\n")
+            return FAILED_EXIT_CODE
+    if base_outcomes is None:
+        sys.stderr.write(WORKTREE_FAILED_MESSAGE.format(revision=base_revision) + "\n")
+        return FAILED_EXIT_CODE
+    base_failure_count = sum(
+        len(each_outcome.failing_identities) for each_outcome in base_outcomes.values()
+    )
+    if base_failure_count == 0:
+        sys.stderr.write(NO_BASE_FAILURE_MESSAGE.format(revision=base_revision) + "\n")
+        return FAILED_EXIT_CODE
+    sys.stdout.write(PROVEN_MESSAGE.format(count=base_failure_count) + "\n")
+    return PASSED_EXIT_CODE
+
+
+def main(all_arguments: list[str]) -> int:
+    """Run the fix test-proof check.
+
+    Args:
+        all_arguments: Command arguments naming the title, base, and repository.
+
+    Returns:
+        0 when the pull request passes, 1 when a fix lacks its proof test.
+    """
+    parsed_arguments = _parse_arguments(all_arguments)
+    if not FIX_TITLE_PATTERN.match(parsed_arguments.title):
+        sys.stdout.write(NOT_A_FIX_MESSAGE + "\n")
+        return PASSED_EXIT_CODE
+    repository_root = Path(parsed_arguments.repository_root).resolve()
+    all_changed_paths = paths_from_git_diff(repository_root, parsed_arguments.base_revision)
+    if not any(
+        is_production_code_path(each_path, repository_root) for each_path in all_changed_paths
+    ):
+        sys.stdout.write(NO_PRODUCTION_CHANGE_MESSAGE + "\n")
+        return PASSED_EXIT_CODE
+    all_changed_tests = _changed_python_tests(all_changed_paths)
+    if not all_changed_tests:
+        sys.stderr.write(NO_CHANGED_TEST_MESSAGE + "\n")
+        return FAILED_EXIT_CODE
+    return _proof_exit_code(all_changed_tests, repository_root, parsed_arguments.base_revision)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/_shared/pr-loop/scripts/pr_loop_shared_constants/fix_pr_test_proof_constants.py

@@ -0,0 +1,43 @@
+"""Constants for the fix pull request test-proof check."""
+
+from __future__ import annotations
+
+import re
+
+FIX_TITLE_PATTERN: re.Pattern[str] = re.compile(r"^fix(\([^)]*\))?!?:")
+ALL_PRODUCTION_CODE_SUFFIXES: tuple[str, ...] = (
+    ".py",
+    ".mjs",
+    ".js",
+    ".cjs",
+    ".ts",
+    ".tsx",
+    ".ps1",
+    ".sh",
+)
+CI_CONFIG_DIRECTORY_NAME: str = ".github"
+PASSED_EXIT_CODE: int = 0
+FAILED_EXIT_CODE: int = 1
+
+NOT_A_FIX_MESSAGE: str = "fix_pr_test_proof: the title is outside the fix type; nothing to prove."
+NO_PRODUCTION_CHANGE_MESSAGE: str = (
+    "fix_pr_test_proof: the fix changes no production code; nothing to prove."
+)
+NO_CHANGED_TEST_MESSAGE: str = (
+    "fix_pr_test_proof: this fix changes production code and no Python test. "
+    "Add a test that fails on the base and passes on the head."
+)
+WORKTREE_FAILED_MESSAGE: str = (
+    "fix_pr_test_proof: git could not check out the base revision {revision}."
+)
+HEAD_FAILURE_MESSAGE: str = (
+    "fix_pr_test_proof: a changed test fails on the head in {group_root}. "
+    "The proof test must pass once the fix is in."
+)
+NO_BASE_FAILURE_MESSAGE: str = (
+    "fix_pr_test_proof: every changed test passes on the base {revision}. "
+    "Add a test that fails without the fix."
+)
+PROVEN_MESSAGE: str = (
+    "fix_pr_test_proof: {count} changed test(s) fail on the base and pass on the head."
+)

package/_shared/pr-loop/scripts/test_fix_pr_test_proof.py

@@ -0,0 +1,126 @@
+"""Behavioral tests for the fix pull request test-proof check.
+
+Every case drives a git repository under ``tmp_path`` and a pytest subprocess,
+the same shape the CI job runs.
+"""
+
+from pathlib import Path
+
+import pytest
+
+import fix_pr_test_proof
+from code_rules_gate_parts.tests._repo_test_helpers import (
+    repository_with_root_pytest_config,
+    run_git,
+)
+
+BUGGY_PRODUCTION_TEXT = (
+    "def add(left: int, right: int) -> int:\n    return left - right\n"
+)
+FIXED_PRODUCTION_TEXT = (
+    "def add(left: int, right: int) -> int:\n    return left + right\n"
+)
+PROOF_TEST_TEXT = (
+    "from calc import add\n\n\ndef test_add_sums_both_operands() -> None:\n"
+    "    assert add(1, 2) == 3\n"
+)
+ALWAYS_PASSING_TEST_TEXT = (
+    "def test_nothing_in_particular() -> None:\n    assert True\n"
+)
+
+
+def _commit_files(repository_root: Path, all_file_texts: dict[str, str]) -> None:
+    for each_relative_path, each_text in all_file_texts.items():
+        file_path = repository_root / each_relative_path
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_text(each_text, encoding="utf-8")
+    run_git(repository_root, "add", "-A")
+    run_git(repository_root, "commit", "--no-verify", "-m", "change")
+
+
+def _head_revision(repository_root: Path) -> str:
+    return run_git(repository_root, "rev-parse", "HEAD").stdout.decode().strip()
+
+
+def _repository_at_buggy_base(tmp_path: Path) -> tuple[Path, str]:
+    repository_root = repository_with_root_pytest_config(tmp_path)
+    _commit_files(repository_root, {"pkg/calc.py": BUGGY_PRODUCTION_TEXT})
+    return repository_root, _head_revision(repository_root)
+
+
+def _run_check(repository_root: Path, title: str, base_revision: str) -> int:
+    return fix_pr_test_proof.main(
+        [
+            "--title",
+            title,
+            "--base",
+            base_revision,
+            "--repository-root",
+            str(repository_root),
+        ]
+    )
+
+
+def test_a_title_outside_the_fix_type_passes(tmp_path: Path) -> None:
+    repository_root, base_revision = _repository_at_buggy_base(tmp_path)
+    _commit_files(repository_root, {"pkg/calc.py": FIXED_PRODUCTION_TEXT})
+
+    assert _run_check(repository_root, "feat: add sums", base_revision) == 0
+
+
+def test_a_fix_that_changes_no_production_code_passes(tmp_path: Path) -> None:
+    repository_root, base_revision = _repository_at_buggy_base(tmp_path)
+    _commit_files(repository_root, {"docs/notes.md": "# Notes\n"})
+
+    assert _run_check(repository_root, "fix(docs): correct a link", base_revision) == 0
+
+
+def test_a_fix_with_no_changed_test_fails(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    repository_root, base_revision = _repository_at_buggy_base(tmp_path)
+    _commit_files(repository_root, {"pkg/calc.py": FIXED_PRODUCTION_TEXT})
+
+    assert _run_check(repository_root, "fix: sum operands", base_revision) == 1
+    assert "no Python test" in capsys.readouterr().err
+
+
+def test_a_fix_whose_test_fails_on_base_and_passes_on_head_passes(
+    tmp_path: Path,
+) -> None:
+    repository_root, base_revision = _repository_at_buggy_base(tmp_path)
+    _commit_files(
+        repository_root,
+        {"pkg/calc.py": FIXED_PRODUCTION_TEXT, "pkg/test_calc.py": PROOF_TEST_TEXT},
+    )
+
+    assert _run_check(repository_root, "fix(calc): sum operands", base_revision) == 0
+
+
+def test_a_fix_whose_changed_test_also_passes_on_base_fails(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    repository_root, base_revision = _repository_at_buggy_base(tmp_path)
+    _commit_files(
+        repository_root,
+        {
+            "pkg/calc.py": FIXED_PRODUCTION_TEXT,
+            "pkg/test_calc.py": ALWAYS_PASSING_TEST_TEXT,
+        },
+    )
+
+    assert _run_check(repository_root, "fix!: sum operands", base_revision) == 1
+    assert "passes on the base" in capsys.readouterr().err
+
+
+def test_a_fix_whose_changed_test_fails_on_head_fails(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    repository_root, base_revision = _repository_at_buggy_base(tmp_path)
+    _commit_files(
+        repository_root,
+        {"pkg/test_calc.py": PROOF_TEST_TEXT, "pkg/extra.py": "VALUE = 1\n"},
+    )
+
+    assert _run_check(repository_root, "fix: sum operands", base_revision) == 1
+    assert "fails on the head" in capsys.readouterr().err

package/bin/codex-skill-load-block.mjs

@@ -0,0 +1,45 @@
+import { lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const SKILL_LOAD_BLOCK_START = '<!-- claude-dev-env skill load: start -->';
+export const SKILL_LOAD_BLOCK_END = '<!-- claude-dev-env skill load: end -->';
+export const SKILL_LOAD_INSTRUCTION = 'Load the pstack:poteto-mode skill before your first tool call or reply: '
+    + 'open its SKILL.md from your skills list and follow it. This binds every Codex agent, '
+    + 'including a helper started with spawn_agent, whatever its task message says.';
+
+const SKILL_LOAD_BLOCK = `${SKILL_LOAD_BLOCK_START}\n${SKILL_LOAD_INSTRUCTION}\n${SKILL_LOAD_BLOCK_END}\n`;
+
+/**
+ * Return the Codex guidance text with the package's skill-load block in it.
+ *
+ * Codex starts a spawn_agent helper without running any hook, so the global
+ * AGENTS.md is the one channel that reaches every helper. A block already in
+ * the text is replaced where it stands; otherwise the block goes first.
+ */
+export function withSkillLoadBlock(guidanceText) {
+    const startIndex = guidanceText.indexOf(SKILL_LOAD_BLOCK_START);
+    const endIndex = startIndex === -1 ? -1 : guidanceText.indexOf(SKILL_LOAD_BLOCK_END, startIndex);
+    if (endIndex === -1) {
+        return guidanceText ? `${SKILL_LOAD_BLOCK}\n${guidanceText}` : SKILL_LOAD_BLOCK;
+    }
+    let afterBlockIndex = endIndex + SKILL_LOAD_BLOCK_END.length;
+    if (guidanceText[afterBlockIndex] === '\n') afterBlockIndex += 1;
+    return guidanceText.slice(0, startIndex) + SKILL_LOAD_BLOCK + guidanceText.slice(afterBlockIndex);
+}
+
+/**
+ * Write the skill-load block into CODEX_HOME/AGENTS.md.
+ *
+ * Returns the file path when the file changed, and null when it already held
+ * the current block.
+ */
+export function writeCodexSkillLoadBlock(codexHome) {
+    const agentsPath = join(codexHome, 'AGENTS.md');
+    const hasGuidance = lstatSync(agentsPath, { throwIfNoEntry: false }) !== undefined;
+    const currentText = hasGuidance ? readFileSync(agentsPath, 'utf8') : '';
+    const updatedText = withSkillLoadBlock(currentText);
+    if (updatedText === currentText) return null;
+    mkdirSync(codexHome, { recursive: true });
+    writeFileSync(agentsPath, updatedText, 'utf8');
+    return agentsPath;
+}

package/bin/codex-skill-load-block.test.mjs

@@ -0,0 +1,72 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+    SKILL_LOAD_BLOCK_END,
+    SKILL_LOAD_BLOCK_START,
+    SKILL_LOAD_INSTRUCTION,
+    withSkillLoadBlock,
+    writeCodexSkillLoadBlock,
+} from './codex-skill-load-block.mjs';
+
+const EXPECTED_BLOCK = `${SKILL_LOAD_BLOCK_START}\n${SKILL_LOAD_INSTRUCTION}\n${SKILL_LOAD_BLOCK_END}\n`;
+
+function makeCodexHome(context) {
+    const root = mkdtempSync(join(tmpdir(), 'cde-skill-load-'));
+    context.after(() => rmSync(root, { recursive: true, force: true }));
+    return join(root, '.codex');
+}
+
+test('the instruction names the skill and binds spawned helpers', () => {
+    assert.match(SKILL_LOAD_INSTRUCTION, /pstack:poteto-mode/);
+    assert.match(SKILL_LOAD_INSTRUCTION, /spawn_agent/);
+});
+
+test('a missing Codex guidance file is created holding only the block', (context) => {
+    const codexHome = makeCodexHome(context);
+
+    const writtenPath = writeCodexSkillLoadBlock(codexHome);
+
+    assert.equal(writtenPath, join(codexHome, 'AGENTS.md'));
+    assert.equal(readFileSync(writtenPath, 'utf8'), EXPECTED_BLOCK);
+});
+
+test('existing guidance keeps every line and gains the block first', (context) => {
+    const codexHome = makeCodexHome(context);
+    mkdirSync(codexHome);
+    writeFileSync(join(codexHome, 'AGENTS.md'), '# pstack model configuration\n\nbug-fix: gpt-6-astra\n');
+
+    writeCodexSkillLoadBlock(codexHome);
+
+    assert.equal(
+        readFileSync(join(codexHome, 'AGENTS.md'), 'utf8'),
+        `${EXPECTED_BLOCK}\n# pstack model configuration\n\nbug-fix: gpt-6-astra\n`,
+    );
+});
+
+test('a repeat install leaves the file unchanged and reports no write', (context) => {
+    const codexHome = makeCodexHome(context);
+    mkdirSync(codexHome);
+    writeFileSync(join(codexHome, 'AGENTS.md'), 'Custom agents\n');
+    writeCodexSkillLoadBlock(codexHome);
+    const afterFirstInstall = readFileSync(join(codexHome, 'AGENTS.md'), 'utf8');
+
+    assert.equal(writeCodexSkillLoadBlock(codexHome), null);
+    assert.equal(readFileSync(join(codexHome, 'AGENTS.md'), 'utf8'), afterFirstInstall);
+});
+
+test('an outdated block is replaced in place and the text around it is kept', () => {
+    const outdated = `Intro\n${SKILL_LOAD_BLOCK_START}\nOld wording\n${SKILL_LOAD_BLOCK_END}\nOutro\n`;
+
+    assert.equal(withSkillLoadBlock(outdated), `Intro\n${EXPECTED_BLOCK}Outro\n`);
+});
+
+test('a start marker with no end marker gets a fresh block and keeps the stray text', () => {
+    const broken = `${SKILL_LOAD_BLOCK_START}\nHalf a block\n`;
+
+    const repaired = withSkillLoadBlock(broken);
+
+    assert.equal(repaired, `${EXPECTED_BLOCK}\n${broken}`);
+});

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

@@ -18,7 +18,7 @@ import {
     writeFileSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CONTENT_DIRECTORIES } from './install.mjs';
 import {
@@ -209,6 +209,81 @@ test('a full install writes skills and agents under .agents and points .claude a
     }
 });
 
+/**
+ * @param {string} hubPath
+ * @returns {string}
+ */
+function resolveHubImportTarget(hubPath) {
+    const hubText = readFileSync(hubPath, 'utf8').trim();
+    assert.match(hubText, /^@\S+$/, 'the Claude hub holds one import line');
+    return resolve(dirname(hubPath), hubText.slice(1));
+}
+
+for (const eachLayout of [
+    { label: 'default home', extraArguments: [], claudeHomeName: '.claude', agentsHomeName: '.agents' },
+    {
+        label: 'profile root',
+        extraArguments: ['--target', '.claude-profile-a'],
+        claudeHomeName: '.claude-profile-a',
+        agentsHomeName: '.claude-profile-a.agents',
+    },
+]) {
+    test(`a ${eachLayout.label} install loads the package guidance from the agents home through the Claude hub`, () => {
+        const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agents-hub-'));
+        const claudeHome = join(homeDirectory, eachLayout.claudeHomeName);
+        const sharedGuidancePath = join(homeDirectory, eachLayout.agentsHomeName, 'AGENTS.md');
+        try {
+            runInstaller(homeDirectory, eachLayout.extraArguments.map(
+                (eachArgument) => (eachArgument.startsWith('.') ? join(homeDirectory, eachArgument) : eachArgument),
+            ));
+
+            assert.equal(
+                readFileSync(sharedGuidancePath, 'utf8'),
+                readFileSync(join(PACKAGE_DIRECTORY, 'AGENTS.md'), 'utf8'),
+                'the package guidance lives once in the agents home',
+            );
+            assert.equal(
+                resolveHubImportTarget(join(claudeHome, 'CLAUDE.md')),
+                sharedGuidancePath,
+                'the Claude hub import resolves to the shared guidance file',
+            );
+            assert.equal(
+                existsSync(join(claudeHome, 'AGENTS.md')),
+                false,
+                'no second guidance copy lands in the Claude home',
+            );
+        } finally {
+            rmSync(homeDirectory, { recursive: true, force: true });
+        }
+    });
+}
+
+test('an upgrade moves the guidance copy an earlier install left in the Claude home into the run backup', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agents-hub-upgrade-'));
+    const claudeHome = join(homeDirectory, '.claude');
+    const retiredGuidancePath = join(claudeHome, 'AGENTS.md');
+    const retiredGuidanceText = 'guidance an earlier install copied here\n';
+    try {
+        runInstaller(homeDirectory, []);
+        writeFileSync(retiredGuidancePath, retiredGuidanceText);
+        const manifestPath = join(claudeHome, '.claude-dev-env-manifest.json');
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        manifest.files.push(retiredGuidancePath);
+        writeFileSync(manifestPath, JSON.stringify(manifest));
+
+        runInstaller(homeDirectory, []);
+
+        assert.equal(existsSync(retiredGuidancePath), false, 'the old Claude-home copy is gone');
+        const backupRoot = join(claudeHome, '.claude-dev-env-pruned');
+        const backupName = readdirSync(backupRoot, { recursive: true })
+            .find(name => name.endsWith('AGENTS.md'));
+        assert.ok(backupName, 'the old copy sits in the run backup');
+        assert.equal(readFileSync(join(backupRoot, backupName), 'utf8'), retiredGuidanceText);
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
 test('installs omit retired agents in each active agents home', () => {
     const runRoot = mkdtempSync(join(tmpdir(), 'cdev-active-roots-'));
     const homeDirectory = join(runRoot, 'home');