claude-dev-env 8.6.1 → 8.7.0

package/scripts/test_agent_merge_check.py

@@ -0,0 +1,317 @@
+"""Tests for the agent merge-readiness check."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIRECTORY))
+
+import agent_merge_check
+from dev_env_scripts_constants.agent_merge_check_constants import (
+    BEHIND_HOLD_REASON,
+    BLOCKED_HOLD_REASON,
+    DIRTY_HOLD_REASON,
+    DRAFT_HOLD_REASON,
+    HOLD_VERDICT_LABEL,
+    MERGE_VERDICT_LABEL,
+    SETTLE_ATTEMPT_COUNT,
+    UNSTABLE_HOLD_REASON,
+)
+
+CLEAN_PULL_REQUEST = {
+    "number": 1442,
+    "draft": False,
+    "mergeable_state": "clean",
+    "head": {"sha": "ab845eb6945650055ebe852312a9057b9f067d6a"},
+}
+
+
+def _pull_request(**all_overrides: object) -> dict[str, object]:
+    return {**CLEAN_PULL_REQUEST, **all_overrides}
+
+
+def test_clean_pull_request_with_no_open_thread_may_merge() -> None:
+    assert agent_merge_check.hold_reason(CLEAN_PULL_REQUEST, 0) is None
+
+
+@pytest.mark.parametrize(
+    ("all_overrides", "expected_reason"),
+    [
+        ({"draft": True}, DRAFT_HOLD_REASON),
+        ({"mergeable_state": "behind"}, BEHIND_HOLD_REASON),
+        ({"mergeable_state": "dirty"}, DIRTY_HOLD_REASON),
+        ({"mergeable_state": "blocked"}, BLOCKED_HOLD_REASON),
+        ({"mergeable_state": "unstable"}, UNSTABLE_HOLD_REASON),
+    ],
+)
+def test_each_unready_state_holds_with_its_own_reason(
+    all_overrides: dict[str, object],
+    expected_reason: str,
+) -> None:
+    assert (
+        agent_merge_check.hold_reason(_pull_request(**all_overrides), 0)
+        == expected_reason
+    )
+
+
+def test_a_draft_holds_even_when_its_merge_state_is_clean() -> None:
+    assert (
+        agent_merge_check.hold_reason(_pull_request(draft=True), 0) == DRAFT_HOLD_REASON
+    )
+
+
+def test_an_unreported_merge_state_holds_and_names_what_github_said() -> None:
+    reason = agent_merge_check.hold_reason(_pull_request(mergeable_state="unknown"), 0)
+    assert reason is not None
+    assert "unknown" in reason
+
+
+def test_an_open_review_thread_holds_a_green_pull_request() -> None:
+    reason = agent_merge_check.hold_reason(CLEAN_PULL_REQUEST, 2)
+    assert reason is not None
+    assert "2" in reason
+
+
+def test_an_open_thread_count_reaches_the_verdict_line() -> None:
+    reason = agent_merge_check.hold_reason(CLEAN_PULL_REQUEST, 1)
+    line = agent_merge_check.verdict_line(
+        "jl-cmd/claude-dev-env", CLEAN_PULL_REQUEST, reason
+    )
+    assert line.startswith(HOLD_VERDICT_LABEL)
+    assert "jl-cmd/claude-dev-env#1442" in line
+
+
+def test_the_ready_verdict_line_names_the_repository_and_head() -> None:
+    line = agent_merge_check.verdict_line(
+        "jl-cmd/claude-dev-env", CLEAN_PULL_REQUEST, None
+    )
+    assert line.startswith(MERGE_VERDICT_LABEL)
+    assert "jl-cmd/claude-dev-env#1442" in line
+    assert "ab845eb" in line
+
+
+def test_a_resolved_thread_and_an_outdated_thread_hold_nothing_back() -> None:
+    all_thread_records = [
+        {"isResolved": True, "isOutdated": False},
+        {"isResolved": False, "isOutdated": True},
+    ]
+    assert agent_merge_check.count_unresolved_threads(all_thread_records) == 0
+
+
+def test_an_unresolved_current_thread_counts() -> None:
+    all_thread_records = [
+        {"isResolved": False, "isOutdated": False},
+        {"isResolved": True, "isOutdated": False},
+        {"isResolved": False, "isOutdated": False},
+    ]
+    assert agent_merge_check.count_unresolved_threads(all_thread_records) == 2
+
+
+def test_a_thread_record_of_another_shape_counts_as_nothing() -> None:
+    assert agent_merge_check.count_unresolved_threads(["", None]) == 0
+
+
+def test_read_pull_request_returns_the_fields_the_api_answered_with(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(
+        agent_merge_check,
+        "_request_json",
+        lambda url, token, all_payload_fields: CLEAN_PULL_REQUEST,
+    )
+    assert (
+        agent_merge_check.read_pull_request("jl-cmd/claude-dev-env", 1442, "token")
+        == CLEAN_PULL_REQUEST
+    )
+
+
+def test_read_pull_request_rejects_an_answer_of_another_shape(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(
+        agent_merge_check,
+        "_request_json",
+        lambda url, token, all_payload_fields: ["not a pull request"],
+    )
+    with pytest.raises(agent_merge_check.MergeCheckError):
+        agent_merge_check.read_pull_request("jl-cmd/claude-dev-env", 1442, "token")
+
+
+def test_read_unresolved_thread_count_reads_the_rest_route(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(
+        agent_merge_check,
+        "_request_json",
+        lambda url, token, all_payload_fields: [
+            {"isResolved": False, "isOutdated": False},
+            {"isResolved": True, "isOutdated": False},
+        ],
+    )
+    assert (
+        agent_merge_check.read_unresolved_thread_count(
+            "jl-cmd/claude-dev-env", 1442, "token"
+        )
+        == 1
+    )
+
+
+def test_read_unresolved_thread_count_falls_back_to_the_query(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def _answer(
+        url: str,
+        token: str,
+        all_payload_fields: object,
+    ) -> object:
+        if all_payload_fields is None:
+            raise agent_merge_check.MergeCheckError("HTTP Error 403: Forbidden")
+        return {
+            "data": {
+                "repository": {
+                    "pullRequest": {
+                        "reviewThreads": {
+                            "nodes": [{"isResolved": False, "isOutdated": False}]
+                        }
+                    }
+                }
+            }
+        }
+
+    monkeypatch.setattr(agent_merge_check, "_request_json", _answer)
+    assert (
+        agent_merge_check.read_unresolved_thread_count(
+            "jl-cmd/claude-dev-env", 1442, "token"
+        )
+        == 1
+    )
+
+
+def test_read_unresolved_thread_count_rejects_a_query_answer_of_another_shape(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def _answer(
+        url: str,
+        token: str,
+        all_payload_fields: object,
+    ) -> object:
+        if all_payload_fields is None:
+            raise agent_merge_check.MergeCheckError("HTTP Error 403: Forbidden")
+        return {"errors": [{"message": "Bad credentials"}]}
+
+    monkeypatch.setattr(agent_merge_check, "_request_json", _answer)
+    with pytest.raises(agent_merge_check.MergeCheckError):
+        agent_merge_check.read_unresolved_thread_count(
+            "jl-cmd/claude-dev-env", 1442, "token"
+        )
+
+
+def test_read_settled_pull_request_reads_again_while_the_state_is_unknown(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    all_answers = [
+        _pull_request(mergeable_state="unknown"),
+        _pull_request(mergeable_state="unknown"),
+        CLEAN_PULL_REQUEST,
+    ]
+    all_waits: list[float] = []
+    monkeypatch.setattr(
+        agent_merge_check,
+        "read_pull_request",
+        lambda slug, number, token: all_answers.pop(0),
+    )
+    settled = agent_merge_check.read_settled_pull_request(
+        "jl-cmd/claude-dev-env", 1442, "token", all_waits.append
+    )
+    assert settled == CLEAN_PULL_REQUEST
+    assert len(all_waits) == 2
+
+
+def test_read_settled_pull_request_stops_after_its_last_attempt(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    all_waits: list[float] = []
+    read_count = 0
+
+    def _unknown(slug: str, number: int, token: str) -> dict[str, object]:
+        nonlocal read_count
+        read_count += 1
+        return _pull_request(mergeable_state="unknown")
+
+    monkeypatch.setattr(agent_merge_check, "read_pull_request", _unknown)
+    settled = agent_merge_check.read_settled_pull_request(
+        "jl-cmd/claude-dev-env", 1442, "token", all_waits.append
+    )
+    assert settled["mergeable_state"] == "unknown"
+    assert read_count == SETTLE_ATTEMPT_COUNT
+    assert len(all_waits) == SETTLE_ATTEMPT_COUNT - 1
+
+
+def test_read_settled_pull_request_waits_for_no_settled_state(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    all_waits: list[float] = []
+    monkeypatch.setattr(
+        agent_merge_check,
+        "read_pull_request",
+        lambda slug, number, token: CLEAN_PULL_REQUEST,
+    )
+    agent_merge_check.read_settled_pull_request(
+        "jl-cmd/claude-dev-env", 1442, "token", all_waits.append
+    )
+    assert all_waits == []
+
+
+def test_a_missing_token_reports_the_error_exit_code(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("GH_TOKEN", raising=False)
+    monkeypatch.delenv("GITHUB_TOKEN", raising=False)
+    assert agent_merge_check.main(["jl-cmd/claude-dev-env", "1442"]) == 2
+
+
+def test_a_ready_pull_request_exits_zero(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("GH_TOKEN", "token")
+    monkeypatch.setattr(
+        agent_merge_check,
+        "read_pull_request",
+        lambda slug, number, token: CLEAN_PULL_REQUEST,
+    )
+    monkeypatch.setattr(agent_merge_check.time, "sleep", lambda seconds: None)
+    monkeypatch.setattr(
+        agent_merge_check,
+        "read_unresolved_thread_count",
+        lambda slug, number, token: 0,
+    )
+    assert agent_merge_check.main(["jl-cmd/claude-dev-env", "1442"]) == 0
+
+
+def test_a_held_pull_request_exits_one(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("GH_TOKEN", "token")
+    monkeypatch.setattr(
+        agent_merge_check,
+        "read_pull_request",
+        lambda slug, number, token: _pull_request(mergeable_state="behind"),
+    )
+    monkeypatch.setattr(
+        agent_merge_check,
+        "read_unresolved_thread_count",
+        lambda slug, number, token: 0,
+    )
+    assert agent_merge_check.main(["jl-cmd/claude-dev-env", "1442"]) == 1
+
+
+def test_an_unreadable_pull_request_exits_two(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def _fail(slug: str, number: int, token: str) -> dict[str, object]:
+        raise agent_merge_check.MergeCheckError("no route to host")
+
+    monkeypatch.setenv("GH_TOKEN", "token")
+    monkeypatch.setattr(agent_merge_check, "read_pull_request", _fail)
+    assert agent_merge_check.main(["jl-cmd/claude-dev-env", "1442"]) == 2

package/scripts/test_durable_post_lint.py

@@ -460,3 +460,49 @@ def should_report_a_rewritten_release_body_through_the_command_line(
     )
     assert completed_process.returncode == 1
     assert "keep the generated text whole" in completed_process.stderr
+
+
+def test_contrast_framing_in_a_body_reports() -> None:
+    all_findings = durable_post_lint.lint_durable_post(
+        action="pr-comment",
+        title=None,
+        body_text="The queue ejected the entry, not the runner.\n",
+    )
+
+    assert [each_finding.code for each_finding in all_findings] == ["contrast-framing"]
+    assert "trailing-comma-not" in all_findings[0].message
+
+
+def test_contrast_framing_in_a_title_reports() -> None:
+    all_findings = durable_post_lint.lint_durable_post(
+        action="pr-create",
+        title="fix(lint): read the base rather than the worktree",
+        body_text=VALID_PR_BODY,
+    )
+
+    assert [each_finding.code for each_finding in all_findings] == ["contrast-framing"]
+    assert "substitution-rather-than" in all_findings[0].message
+
+
+def test_a_body_stating_what_is_stays_clean() -> None:
+    all_findings = durable_post_lint.lint_durable_post(
+        action="pr-comment",
+        title=None,
+        body_text="The queue ejected the entry. The runner stayed up.\n",
+    )
+
+    assert all_findings == ()
+
+
+def test_a_release_body_carrying_a_contrast_stays_accepted() -> None:
+    all_findings = durable_post_lint.lint_durable_post(
+        action="pr-edit",
+        title=None,
+        body_text=RELEASE_BODY.replace(
+            "This PR was generated with",
+            "Bumped rather than pinned. This PR was generated with",
+        ),
+        head_branch=RELEASE_BRANCH,
+    )
+
+    assert all_findings == ()

package/scripts/test_followup_cli.py

@@ -9,6 +9,8 @@ from pathlib import Path
 
 from dev_env_scripts_constants.followup_constants import (
     BACKLOG_EXCEEDED_EXIT_CODE,
+    BACKLOG_EXCEEDED_TEMPLATE,
+    BACKLOG_WITHIN_TEMPLATE,
     FOLLOWUP_BACKLOG_THRESHOLD,
 )
 from followup_cli import main
@@ -251,6 +253,44 @@ def test_count_escalates_once_the_backlog_passes_the_threshold(
     assert str(FOLLOWUP_BACKLOG_THRESHOLD) in output_text
 
 
+def test_count_writes_the_within_threshold_template_verbatim(
+    tmp_path: Path,
+) -> None:
+    exit_code, output_text = run_command(["count", "--repository-root", str(tmp_path)])
+
+    assert exit_code == 0
+    assert output_text == (
+        BACKLOG_WITHIN_TEMPLATE.format(
+            finding_count=0, threshold=FOLLOWUP_BACKLOG_THRESHOLD
+        )
+        + "\n"
+    )
+
+
+def test_count_writes_the_exceeded_template_verbatim(tmp_path: Path) -> None:
+    for each_index in range(FOLLOWUP_BACKLOG_THRESHOLD + 1):
+        record_followup_finding(
+            tmp_path,
+            FollowupFinding(
+                "code-rules",
+                f"run{each_index}.py",
+                "one smell",
+                f"code-rules/x{each_index}",
+            ),
+        )
+
+    exit_code, output_text = run_command(["count", "--repository-root", str(tmp_path)])
+
+    assert exit_code == BACKLOG_EXCEEDED_EXIT_CODE
+    assert output_text == (
+        BACKLOG_EXCEEDED_TEMPLATE.format(
+            finding_count=FOLLOWUP_BACKLOG_THRESHOLD + 1,
+            threshold=FOLLOWUP_BACKLOG_THRESHOLD,
+        )
+        + "\n"
+    )
+
+
 def test_list_names_the_check_behind_each_finding(tmp_path: Path) -> None:
     record_followup_finding(
         tmp_path,

package/scripts/test_merge_gate_checks.py

@@ -0,0 +1,92 @@
+"""Specifications for holding a merge policy document to its branch ruleset."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from merge_gate_checks import (
+    main,
+    missing_contexts,
+    parse_declared_contexts,
+    ruleset_contexts,
+)
+
+REPOSITORY_ROOT = Path(__file__).resolve().parents[3]
+POLICY_DOCUMENT_PATH = REPOSITORY_ROOT / "docs" / "merge-policy.md"
+RULESET_SNAPSHOT_PATH = REPOSITORY_ROOT / "docs" / "merge-policy-ruleset.json"
+INSTRUCTION_PAIRS_CONTEXT = "instruction-pairs / instruction-pairs"
+UTF8_ENCODING = "utf-8"
+
+
+def _ruleset_with_contexts(*all_contexts: str) -> list[dict[str, object]]:
+    return [
+        {"type": "deletion"},
+        {
+            "type": "required_status_checks",
+            "parameters": {
+                "required_status_checks": [
+                    {"context": each_context, "integration_id": 15368}
+                    for each_context in all_contexts
+                ]
+            },
+        },
+    ]
+
+
+def should_read_the_contexts_the_fenced_block_declares() -> None:
+    document_text = (
+        "# Merge policy\n\n"
+        "```required-status-checks\n"
+        f"{INSTRUCTION_PAIRS_CONTEXT}\n"
+        "```\n\n"
+        "```\n"
+        "python merge_gate_checks.py --refresh\n"
+        "```\n"
+    )
+
+    assert parse_declared_contexts(document_text) == [INSTRUCTION_PAIRS_CONTEXT]
+
+
+def should_ignore_a_document_with_no_declaration_block() -> None:
+    assert parse_declared_contexts("# Merge policy\n\nNo block here.\n") == []
+
+
+def should_read_every_context_the_ruleset_requires() -> None:
+    payload = _ruleset_with_contexts(INSTRUCTION_PAIRS_CONTEXT, "Ruff")
+
+    assert ruleset_contexts(payload) == {INSTRUCTION_PAIRS_CONTEXT, "Ruff"}
+
+
+def should_report_a_check_the_ruleset_stopped_requiring() -> None:
+    document_text = f"```required-status-checks\n{INSTRUCTION_PAIRS_CONTEXT}\n```\n"
+
+    assert missing_contexts(document_text, _ruleset_with_contexts("Ruff")) == [
+        INSTRUCTION_PAIRS_CONTEXT
+    ]
+
+
+def should_find_every_check_the_checked_in_policy_names() -> None:
+    document_text = POLICY_DOCUMENT_PATH.read_text(encoding=UTF8_ENCODING)
+    ruleset_payload = json.loads(
+        RULESET_SNAPSHOT_PATH.read_text(encoding=UTF8_ENCODING)
+    )
+
+    assert parse_declared_contexts(document_text)
+    assert missing_contexts(document_text, ruleset_payload) == []
+
+
+def should_exit_non_zero_when_a_named_check_left_the_ruleset(tmp_path: Path) -> None:
+    document_path = tmp_path / "merge-policy.md"
+    document_path.write_text(
+        f"```required-status-checks\n{INSTRUCTION_PAIRS_CONTEXT}\n```\n",
+        encoding=UTF8_ENCODING,
+    )
+    ruleset_path = tmp_path / "merge-policy-ruleset.json"
+    ruleset_path.write_text(
+        json.dumps(_ruleset_with_contexts("Ruff")), encoding=UTF8_ENCODING
+    )
+
+    exit_code = main(["--document", str(document_path), "--ruleset", str(ruleset_path)])
+
+    assert exit_code == 1

package/scripts/tests/test_code_review_constants.py

@@ -0,0 +1,78 @@
+"""Specifications for the permission modes the review binary is asked for.
+
+The review binary accepts one permission mode for an ordinary caller and a
+different one for root. Naming the wrong mode means the binary refuses the
+call, no review runs, and no stamp is ever minted.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+
+import pytest
+from dev_env_scripts_constants import code_review_constants
+
+BYPASS_MODE_TOKEN: str = "bypassPermissions"
+ACCEPT_EDITS_MODE_TOKEN: str = "acceptEdits"
+ROOT_USER_ID: int = 0
+UNPRIVILEGED_USER_ID: int = 1000
+
+
+def _permission_mode_seen_by(
+    monkeypatch: pytest.MonkeyPatch, effective_user_id: int
+) -> str:
+    """Read the review permission mode a caller with this user id resolves."""
+    monkeypatch.setattr(os, "geteuid", lambda: effective_user_id)
+    reloaded_constants = importlib.reload(code_review_constants)
+    return str(reloaded_constants.REVIEW_PERMISSION_MODE)
+
+
+def test_root_detection_agrees_with_this_process(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(os, "geteuid", lambda: ROOT_USER_ID)
+    reloaded_constants = importlib.reload(code_review_constants)
+
+    assert reloaded_constants.IS_ROOT_CALLER is True
+    assert reloaded_constants.ROOT_EFFECTIVE_USER_ID == ROOT_USER_ID
+
+
+def test_bypass_mode_names_the_token_the_binary_reads() -> None:
+    assert code_review_constants.PERMISSION_MODE_BYPASS == BYPASS_MODE_TOKEN
+
+
+def test_accept_edits_mode_names_the_token_the_binary_reads() -> None:
+    assert code_review_constants.PERMISSION_MODE_ACCEPT_EDITS == ACCEPT_EDITS_MODE_TOKEN
+
+
+def test_a_root_caller_resolves_the_mode_the_binary_accepts(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    assert _permission_mode_seen_by(monkeypatch, ROOT_USER_ID) == (
+        ACCEPT_EDITS_MODE_TOKEN
+    )
+
+
+def test_an_ordinary_caller_resolves_the_bypass_mode(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    assert _permission_mode_seen_by(monkeypatch, UNPRIVILEGED_USER_ID) == (
+        BYPASS_MODE_TOKEN
+    )
+
+
+def test_a_platform_without_a_user_id_still_loads_the_constants(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Windows exposes no ``os.geteuid``, and the module still imports.
+
+    Reading a missing ``os.geteuid`` raises, and every caller of the review
+    invoker dies at import. A platform that reports no user id is never the
+    root the review binary refuses, so it reads as an ordinary caller.
+    """
+    monkeypatch.delattr(os, "geteuid", raising=False)
+    reloaded_constants = importlib.reload(code_review_constants)
+
+    assert reloaded_constants.IS_ROOT_CALLER is False
+    assert reloaded_constants.REVIEW_PERMISSION_MODE == BYPASS_MODE_TOKEN

package/scripts/tests/test_codex_compat_materializer.py

@@ -173,9 +173,9 @@ def test_public_legacy_call_forms_validate_collection_entries(tmp_path: Path) ->
         publish_plan(config, all_planned_files=[object()])
 
 
-def test_render_codex_failure_blast_radius_requires_the_excerpt_heading() -> None:
-    with pytest.raises(MaterializerError, match="requires a Codex excerpt"):
-        materializer.render_codex_failure_blast_radius("# No excerpt\n")
+def test_render_codex_instruction_excerpt_requires_the_excerpt_heading() -> None:
+    with pytest.raises(MaterializerError, match="rules/correction-lens.md requires a Codex excerpt"):
+        materializer.render_codex_instruction_excerpt("# No excerpt\n", "rules/correction-lens.md")
 
 
 def test_validation_rejects_reparse_point_from_portable_attribute_seam(
@@ -823,13 +823,57 @@ def test_failure_blast_radius_projection_uses_the_canonical_excerpt() -> None:
     canonical_rule_path = Path(__file__).parents[2] / "rules" / "failure-blast-radius.md"
     canonical_rule = canonical_rule_path.read_text(encoding="utf-8")
 
-    projected_instruction = materializer.render_codex_failure_blast_radius(canonical_rule)
+    projected_instruction = materializer.render_codex_instruction_excerpt(
+        canonical_rule, "rules/failure-blast-radius.md"
+    )
 
     assert projected_instruction.startswith("Failure handling for this run")
     assert "Three attempts, then park." in projected_instruction
     assert "Report as: N of M complete" in projected_instruction
 
 
+def test_codex_instruction_projection_carries_every_listed_rule(tmp_path: Path) -> None:
+    rules_root = Path(__file__).parents[2] / "rules"
+    source = tmp_path / "source"
+    target = tmp_path / "target"
+    (source / "rules").mkdir(parents=True)
+    for each_relative_path in materializer.codex_instruction_rule_relative_paths:
+        canonical_path = rules_root / Path(each_relative_path).name
+        (source / each_relative_path).write_text(
+            canonical_path.read_text(encoding="utf-8"), encoding="utf-8"
+        )
+    config = MaterializerConfig(source, target, should_apply=True)
+
+    planned, report = build_plan(config, all_agents=[])
+    publish_plan(config, planned, report)
+
+    projected_instruction = (target / "AGENTS.md").read_text(encoding="utf-8")
+    assert "Failure handling for this run" in projected_instruction
+    assert "Correction handling for this run" in projected_instruction
+    manifest_record = _manifest_files(_required_manifest_path(config))["AGENTS.md"]
+    assert manifest_record["source"] == "rules/failure-blast-radius.md, rules/correction-lens.md"
+
+
+def test_codex_instruction_projection_skips_an_absent_listed_rule(
+    tmp_path: Path,
+) -> None:
+    rules_root = Path(__file__).parents[2] / "rules"
+    source = tmp_path / "source"
+    (source / "rules").mkdir(parents=True)
+    (source / "rules" / "correction-lens.md").write_text(
+        (rules_root / "correction-lens.md").read_text(encoding="utf-8"),
+        encoding="utf-8",
+    )
+    config = MaterializerConfig(source, tmp_path / "target", should_apply=False)
+
+    projection = materializer._build_codex_instruction_projection(config)
+
+    assert projection is not None
+    assert projection.source_identity == "rules/correction-lens.md"
+    assert "Correction handling for this run" in projection.content
+    assert "Failure handling for this run" not in projection.content
+
+
 def test_build_plan_publishes_owned_agents_projection_and_tracks_drift(
     tmp_path: Path,
 ) -> None: