claude-dev-env 8.11.0 → 8.11.1

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

@@ -5,22 +5,33 @@
     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
+    title "fix: ..." with no changed Python or Node test -> fail
     changed test passes on head, fails on base      -> pass
     changed test passes on both                     -> fail
+    any changed test fails on head                  -> fail
 
-The base run reuses the regression gate's detached worktree: the changed test
+Python tests reuse 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.
+Node tests (``*.test.mjs``, ``*.test.js``, ``*.test.cjs``) run through
+``node --test`` on the head, then on a detached base checkout that holds a copy
+of the changed test files. The fix is proven when at least one language's
+changed tests fail on the base.
 """
 
 import argparse
+import shutil
+import subprocess
 import sys
+import tempfile
+from enum import Enum
 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_NODE_TEST_COMMAND,
+    ALL_NODE_TEST_SUFFIXES,
     ALL_PRODUCTION_CODE_SUFFIXES,
     CI_CONFIG_DIRECTORY_NAME,
     FAILED_EXIT_CODE,
@@ -29,6 +40,8 @@ from pr_loop_shared_constants.fix_pr_test_proof_constants import (
     NO_BASE_FAILURE_MESSAGE,
     NO_CHANGED_TEST_MESSAGE,
     NO_PRODUCTION_CHANGE_MESSAGE,
+    NODE_BASE_WORKTREE_DIRECTORY_NAME,
+    NODE_BASE_WORKTREE_TEMP_DIRECTORY_PREFIX,
     NOT_A_FIX_MESSAGE,
     PASSED_EXIT_CODE,
     PROVEN_MESSAGE,
@@ -36,6 +49,15 @@ from pr_loop_shared_constants.fix_pr_test_proof_constants import (
 )
 
 
+class ProofVerdict(Enum):
+    """The result of running one language's changed tests on the head and the base."""
+
+    HEAD_FAILED = "head_failed"
+    BASE_UNAVAILABLE = "base_unavailable"
+    PASSES_ON_BASE = "passes_on_base"
+    PROVEN = "proven"
+
+
 def _parse_arguments(all_arguments: list[str]) -> argparse.Namespace:
     parser = argparse.ArgumentParser(prog="fix_pr_test_proof")
     parser.add_argument("--title", required=True)
@@ -72,9 +94,17 @@ def _changed_python_tests(all_changed_paths: list[Path]) -> list[Path]:
     ]
 
 
-def _proof_exit_code(
+def _changed_node_tests(all_changed_paths: list[Path]) -> list[Path]:
+    return [
+        each_path
+        for each_path in all_changed_paths
+        if each_path.name.endswith(ALL_NODE_TEST_SUFFIXES) and each_path.is_file()
+    ]
+
+
+def _python_proof_verdict(
     all_changed_tests: list[Path], repository_root: Path, base_revision: str
-) -> int:
+) -> ProofVerdict:
     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
@@ -87,18 +117,78 @@ def _proof_exit_code(
     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
+            return ProofVerdict.HEAD_FAILED
     if base_outcomes is None:
         sys.stderr.write(WORKTREE_FAILED_MESSAGE.format(revision=base_revision) + "\n")
-        return FAILED_EXIT_CODE
+        return ProofVerdict.BASE_UNAVAILABLE
     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
+        return ProofVerdict.PASSES_ON_BASE
     sys.stdout.write(PROVEN_MESSAGE.format(count=base_failure_count) + "\n")
-    return PASSED_EXIT_CODE
+    return ProofVerdict.PROVEN
+
+
+def _node_tests_pass(working_directory: Path, all_relative_tests: list[Path]) -> bool:
+    node_run = subprocess.run(
+        [*ALL_NODE_TEST_COMMAND, *(each_path.as_posix() for each_path in all_relative_tests)],
+        cwd=working_directory,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return node_run.returncode == 0
+
+
+def _copy_tests_onto(
+    base_worktree: Path, repository_root: Path, all_relative_tests: list[Path]
+) -> None:
+    for each_relative_test in all_relative_tests:
+        base_test_path = base_worktree / each_relative_test
+        base_test_path.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(repository_root / each_relative_test, base_test_path)
+
+
+def _node_proof_verdict(
+    all_changed_tests: list[Path], repository_root: Path, base_revision: str
+) -> ProofVerdict:
+    all_relative_tests = [each_path.relative_to(repository_root) for each_path in all_changed_tests]
+    if not _node_tests_pass(repository_root, all_relative_tests):
+        sys.stderr.write(HEAD_FAILURE_MESSAGE.format(group_root=repository_root) + "\n")
+        return ProofVerdict.HEAD_FAILED
+    with tempfile.TemporaryDirectory(
+        prefix=NODE_BASE_WORKTREE_TEMP_DIRECTORY_PREFIX, ignore_cleanup_errors=True
+    ) as base_parent_text:
+        base_worktree = Path(base_parent_text) / NODE_BASE_WORKTREE_DIRECTORY_NAME
+        if not staged_test_regression._add_baseline_worktree(
+            repository_root, base_worktree, base_revision
+        ):
+            sys.stderr.write(WORKTREE_FAILED_MESSAGE.format(revision=base_revision) + "\n")
+            return ProofVerdict.BASE_UNAVAILABLE
+        try:
+            _copy_tests_onto(base_worktree, repository_root, all_relative_tests)
+            passes_on_base = _node_tests_pass(base_worktree, all_relative_tests)
+        finally:
+            staged_test_regression._remove_baseline_worktree(repository_root, base_worktree)
+    if passes_on_base:
+        return ProofVerdict.PASSES_ON_BASE
+    sys.stdout.write(PROVEN_MESSAGE.format(count=len(all_relative_tests)) + "\n")
+    return ProofVerdict.PROVEN
+
+
+def _proof_exit_code(
+    all_verdicts: list[ProofVerdict], base_revision: str
+) -> int:
+    if any(
+        each_verdict in (ProofVerdict.HEAD_FAILED, ProofVerdict.BASE_UNAVAILABLE)
+        for each_verdict in all_verdicts
+    ):
+        return FAILED_EXIT_CODE
+    if ProofVerdict.PROVEN in all_verdicts:
+        return PASSED_EXIT_CODE
+    sys.stderr.write(NO_BASE_FAILURE_MESSAGE.format(revision=base_revision) + "\n")
+    return FAILED_EXIT_CODE
 
 
 def main(all_arguments: list[str]) -> int:
@@ -121,11 +211,22 @@ def main(all_arguments: list[str]) -> int:
     ):
         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:
+    all_changed_python_tests = _changed_python_tests(all_changed_paths)
+    all_changed_node_tests = _changed_node_tests(all_changed_paths)
+    if not all_changed_python_tests and not all_changed_node_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)
+    base_revision = parsed_arguments.base_revision
+    all_verdicts: list[ProofVerdict] = []
+    if all_changed_python_tests:
+        all_verdicts.append(
+            _python_proof_verdict(all_changed_python_tests, repository_root, base_revision)
+        )
+    if all_changed_node_tests:
+        all_verdicts.append(
+            _node_proof_verdict(all_changed_node_tests, repository_root, base_revision)
+        )
+    return _proof_exit_code(all_verdicts, base_revision)
 
 
 if __name__ == "__main__":

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

@@ -15,6 +15,10 @@ ALL_PRODUCTION_CODE_SUFFIXES: tuple[str, ...] = (
     ".ps1",
     ".sh",
 )
+ALL_NODE_TEST_SUFFIXES: tuple[str, ...] = (".test.mjs", ".test.js", ".test.cjs")
+ALL_NODE_TEST_COMMAND: tuple[str, ...] = ("node", "--test")
+NODE_BASE_WORKTREE_TEMP_DIRECTORY_PREFIX: str = "fix_pr_test_proof_node_base_"
+NODE_BASE_WORKTREE_DIRECTORY_NAME: str = "tree"
 CI_CONFIG_DIRECTORY_NAME: str = ".github"
 PASSED_EXIT_CODE: int = 0
 FAILED_EXIT_CODE: int = 1
@@ -24,7 +28,7 @@ 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. "
+    "fix_pr_test_proof: this fix changes production code and no Python or Node test. "
     "Add a test that fails on the base and passes on the head."
 )
 WORKTREE_FAILED_MESSAGE: str = (

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

@@ -1,7 +1,7 @@
 """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.
+Every case drives a git repository under ``tmp_path`` and a pytest or
+``node --test`` subprocess, the same shape the CI job runs.
 """
 
 from pathlib import Path
@@ -27,6 +27,18 @@ PROOF_TEST_TEXT = (
 ALWAYS_PASSING_TEST_TEXT = (
     "def test_nothing_in_particular() -> None:\n    assert True\n"
 )
+BUGGY_NODE_PRODUCTION_TEXT = "export function add(left, right) {\n    return left - right;\n}\n"
+FIXED_NODE_PRODUCTION_TEXT = "export function add(left, right) {\n    return left + right;\n}\n"
+NODE_PROOF_TEST_TEXT = (
+    "import { test } from 'node:test';\n"
+    "import { strict as assert } from 'node:assert';\n"
+    "import { add } from './calc.mjs';\n\n"
+    "test('add sums both operands', () => {\n    assert.equal(add(1, 2), 3);\n});\n"
+)
+NODE_ALWAYS_PASSING_TEST_TEXT = (
+    "import { test } from 'node:test';\n\n"
+    "test('nothing in particular', () => {});\n"
+)
 
 
 def _commit_files(repository_root: Path, all_file_texts: dict[str, str]) -> None:
@@ -48,6 +60,12 @@ def _repository_at_buggy_base(tmp_path: Path) -> tuple[Path, str]:
     return repository_root, _head_revision(repository_root)
 
 
+def _repository_at_buggy_node_base(tmp_path: Path) -> tuple[Path, str]:
+    repository_root = repository_with_root_pytest_config(tmp_path)
+    _commit_files(repository_root, {"bin/calc.mjs": BUGGY_NODE_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(
         [
@@ -82,7 +100,7 @@ def test_a_fix_with_no_changed_test_fails(
     _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
+    assert "no Python or Node test" in capsys.readouterr().err
 
 
 def test_a_fix_whose_test_fails_on_base_and_passes_on_head_passes(
@@ -124,3 +142,45 @@ def test_a_fix_whose_changed_test_fails_on_head_fails(
 
     assert _run_check(repository_root, "fix: sum operands", base_revision) == 1
     assert "fails on the head" in capsys.readouterr().err
+
+
+def test_a_node_fix_whose_test_fails_on_base_and_passes_on_head_passes(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    repository_root, base_revision = _repository_at_buggy_node_base(tmp_path)
+    _commit_files(
+        repository_root,
+        {"bin/calc.mjs": FIXED_NODE_PRODUCTION_TEXT, "bin/calc.test.mjs": NODE_PROOF_TEST_TEXT},
+    )
+
+    assert _run_check(repository_root, "fix(bin): sum operands", base_revision) == 0
+    assert "fail on the base and pass on the head" in capsys.readouterr().out
+
+
+def test_a_node_fix_whose_changed_test_also_passes_on_base_fails(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    repository_root, base_revision = _repository_at_buggy_node_base(tmp_path)
+    _commit_files(
+        repository_root,
+        {
+            "bin/calc.mjs": FIXED_NODE_PRODUCTION_TEXT,
+            "bin/calc.test.mjs": NODE_ALWAYS_PASSING_TEST_TEXT,
+        },
+    )
+
+    assert _run_check(repository_root, "fix(bin): sum operands", base_revision) == 1
+    assert "passes on the base" in capsys.readouterr().err
+
+
+def test_a_node_fix_whose_changed_test_fails_on_head_fails(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    repository_root, base_revision = _repository_at_buggy_node_base(tmp_path)
+    _commit_files(
+        repository_root,
+        {"bin/calc.test.mjs": NODE_PROOF_TEST_TEXT, "bin/extra.mjs": "export const VALUE = 1;\n"},
+    )
+
+    assert _run_check(repository_root, "fix(bin): sum operands", base_revision) == 1
+    assert "fails on the head" in capsys.readouterr().err

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

@@ -1,13 +1,29 @@
-import { lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { lstatSync, mkdirSync, readFileSync, readlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } 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.';
+export const PACKAGE_GUIDANCE_BLOCK_START = '<!-- claude-dev-env package guidance: start -->';
+export const PACKAGE_GUIDANCE_BLOCK_END = '<!-- claude-dev-env package guidance: end -->';
 
-const SKILL_LOAD_BLOCK = `${SKILL_LOAD_BLOCK_START}\n${SKILL_LOAD_INSTRUCTION}\n${SKILL_LOAD_BLOCK_END}\n`;
+const WINDOWS_LONG_PATH_PREFIX = '\\\\?\\';
+
+function managedBlock(blockStart, blockBody, blockEnd) {
+    const terminatedBody = blockBody.endsWith('\n') ? blockBody : `${blockBody}\n`;
+    return `${blockStart}\n${terminatedBody}${blockEnd}\n`;
+}
+
+function withBlockReplaced(guidanceText, blockStart, blockEnd, block) {
+    const startIndex = guidanceText.indexOf(blockStart);
+    const endIndex = startIndex === -1 ? -1 : guidanceText.indexOf(blockEnd, startIndex);
+    if (endIndex === -1) return null;
+    let afterBlockIndex = endIndex + blockEnd.length;
+    if (guidanceText[afterBlockIndex] === '\n') afterBlockIndex += 1;
+    return guidanceText.slice(0, startIndex) + block + guidanceText.slice(afterBlockIndex);
+}
 
 /**
  * Return the Codex guidance text with the package's skill-load block in it.
@@ -17,29 +33,61 @@ const SKILL_LOAD_BLOCK = `${SKILL_LOAD_BLOCK_START}\n${SKILL_LOAD_INSTRUCTION}\n
  * 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);
+    const block = managedBlock(SKILL_LOAD_BLOCK_START, SKILL_LOAD_INSTRUCTION, SKILL_LOAD_BLOCK_END);
+    const replacedText = withBlockReplaced(guidanceText, SKILL_LOAD_BLOCK_START, SKILL_LOAD_BLOCK_END, block);
+    if (replacedText !== null) return replacedText;
+    return guidanceText ? `${block}\n${guidanceText}` : block;
+}
+
+function withPackageGuidanceBlock(guidanceText, packageGuidanceText) {
+    const block = managedBlock(PACKAGE_GUIDANCE_BLOCK_START, packageGuidanceText, PACKAGE_GUIDANCE_BLOCK_END);
+    const replacedText = withBlockReplaced(
+        guidanceText,
+        PACKAGE_GUIDANCE_BLOCK_START,
+        PACKAGE_GUIDANCE_BLOCK_END,
+        block,
+    );
+    return replacedText ?? `${guidanceText}\n${block}`;
+}
+
+function comparablePath(filePath) {
+    const withoutPrefix = filePath.startsWith(WINDOWS_LONG_PATH_PREFIX)
+        ? filePath.slice(WINDOWS_LONG_PATH_PREFIX.length)
+        : filePath;
+    const resolvedPath = resolve(withoutPrefix);
+    return process.platform === 'win32' ? resolvedPath.toLowerCase() : resolvedPath;
+}
+
+function linksToPackageGuidance(agentsPath, allPackageGuidancePaths) {
+    const linkTarget = comparablePath(resolve(dirname(agentsPath), readlinkSync(agentsPath)));
+    return allPackageGuidancePaths.some(eachPath => comparablePath(eachPath) === linkTarget);
 }
 
 /**
- * Write the skill-load block into CODEX_HOME/AGENTS.md.
+ * Keep CODEX_HOME/AGENTS.md carrying the skill-load block.
+ *
+ * A symbolic link that points at the package guidance (the shared agents-home
+ * copy, or the retired copy under the Claude home) is replaced by a regular
+ * file holding the skill-load block and a package-guidance block, so Codex
+ * keeps both after the package moves its guidance. A file that already holds
+ * the package-guidance block gets the current guidance text. A link to any
+ * other file is left alone.
  *
- * Returns the file path when the file changed, and null when it already held
- * the current block.
+ * Returns the file path when the file changed, and null otherwise.
  */
-export function writeCodexSkillLoadBlock(codexHome) {
+export function writeCodexAgentsGuidance(codexHome, packageGuidanceText, allPackageGuidancePaths) {
     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;
+    const agentsEntry = lstatSync(agentsPath, { throwIfNoEntry: false });
+    const isPackageGuidanceLink = agentsEntry?.isSymbolicLink() ?? false;
+    if (isPackageGuidanceLink && !linksToPackageGuidance(agentsPath, allPackageGuidancePaths)) return null;
+    const currentText = agentsEntry && !isPackageGuidanceLink ? readFileSync(agentsPath, 'utf8') : '';
+    let updatedText = withSkillLoadBlock(currentText);
+    if (isPackageGuidanceLink || updatedText.includes(PACKAGE_GUIDANCE_BLOCK_START)) {
+        updatedText = withPackageGuidanceBlock(updatedText, packageGuidanceText);
+    }
+    if (!isPackageGuidanceLink && updatedText === currentText) return null;
     mkdirSync(codexHome, { recursive: true });
+    if (isPackageGuidanceLink) unlinkSync(agentsPath);
     writeFileSync(agentsPath, updatedText, 'utf8');
     return agentsPath;
 }

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

@@ -1,22 +1,43 @@
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
-import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { lstatSync, mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
+    PACKAGE_GUIDANCE_BLOCK_END,
+    PACKAGE_GUIDANCE_BLOCK_START,
     SKILL_LOAD_BLOCK_END,
     SKILL_LOAD_BLOCK_START,
     SKILL_LOAD_INSTRUCTION,
     withSkillLoadBlock,
-    writeCodexSkillLoadBlock,
+    writeCodexAgentsGuidance,
 } from './codex-skill-load-block.mjs';
 
 const EXPECTED_BLOCK = `${SKILL_LOAD_BLOCK_START}\n${SKILL_LOAD_INSTRUCTION}\n${SKILL_LOAD_BLOCK_END}\n`;
+const PACKAGE_GUIDANCE = 'Status\n\nChanged / proof / blocked.\n';
 
-function makeCodexHome(context) {
+function guidanceBlock(guidanceText) {
+    return `${PACKAGE_GUIDANCE_BLOCK_START}\n${guidanceText}${PACKAGE_GUIDANCE_BLOCK_END}\n`;
+}
+
+function makeHomes(context) {
     const root = mkdtempSync(join(tmpdir(), 'cde-skill-load-'));
     context.after(() => rmSync(root, { recursive: true, force: true }));
-    return join(root, '.codex');
+    const codexHome = join(root, '.codex');
+    const retiredGuidancePath = join(root, '.claude', 'AGENTS.md');
+    const sharedGuidancePath = join(root, '.agents', 'AGENTS.md');
+    return {
+        root,
+        codexHome,
+        agentsPath: join(codexHome, 'AGENTS.md'),
+        retiredGuidancePath,
+        sharedGuidancePath,
+        allPackageGuidancePaths: [retiredGuidancePath, sharedGuidancePath],
+    };
+}
+
+function writeGuidance(homes) {
+    return writeCodexAgentsGuidance(homes.codexHome, PACKAGE_GUIDANCE, homes.allPackageGuidancePaths);
 }
 
 test('the instruction names the skill and binds spawned helpers', () => {
@@ -24,37 +45,37 @@ test('the instruction names the skill and binds spawned helpers', () => {
     assert.match(SKILL_LOAD_INSTRUCTION, /spawn_agent/);
 });
 
-test('a missing Codex guidance file is created holding only the block', (context) => {
-    const codexHome = makeCodexHome(context);
+test('a missing Codex guidance file is created holding only the skill-load block', (context) => {
+    const homes = makeHomes(context);
 
-    const writtenPath = writeCodexSkillLoadBlock(codexHome);
+    const writtenPath = writeGuidance(homes);
 
-    assert.equal(writtenPath, join(codexHome, 'AGENTS.md'));
-    assert.equal(readFileSync(writtenPath, 'utf8'), EXPECTED_BLOCK);
+    assert.equal(writtenPath, homes.agentsPath);
+    assert.equal(readFileSync(homes.agentsPath, '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');
+test('existing guidance keeps every line and gains the skill-load block first', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    writeFileSync(homes.agentsPath, '# pstack model configuration\n\nbug-fix: gpt-6-astra\n');
 
-    writeCodexSkillLoadBlock(codexHome);
+    writeGuidance(homes);
 
     assert.equal(
-        readFileSync(join(codexHome, 'AGENTS.md'), 'utf8'),
+        readFileSync(homes.agentsPath, '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);
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    writeFileSync(homes.agentsPath, 'Custom agents\n');
+    writeGuidance(homes);
+    const afterFirstInstall = readFileSync(homes.agentsPath, 'utf8');
+
+    assert.equal(writeGuidance(homes), null);
+    assert.equal(readFileSync(homes.agentsPath, 'utf8'), afterFirstInstall);
 });
 
 test('an outdated block is replaced in place and the text around it is kept', () => {
@@ -66,7 +87,48 @@ test('an outdated block is replaced in place and the text around it is kept', ()
 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(withSkillLoadBlock(broken), `${EXPECTED_BLOCK}\n${broken}`);
+});
+
+for (const linkName of ['retiredGuidancePath', 'sharedGuidancePath']) {
+    test(`a link to package guidance at ${linkName} becomes a file with both blocks`, (context) => {
+        const homes = makeHomes(context);
+        mkdirSync(homes.codexHome);
+        symlinkSync(homes[linkName], homes.agentsPath);
+
+        const writtenPath = writeGuidance(homes);
+
+        assert.equal(writtenPath, homes.agentsPath);
+        assert.equal(lstatSync(homes.agentsPath).isSymbolicLink(), false);
+        assert.equal(
+            readFileSync(homes.agentsPath, 'utf8'),
+            `${EXPECTED_BLOCK}\n${guidanceBlock(PACKAGE_GUIDANCE)}`,
+        );
+    });
+}
+
+test('a converted file takes the new package guidance on the next install', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    writeFileSync(homes.agentsPath, `${EXPECTED_BLOCK}\n${guidanceBlock('Old guidance\n')}`);
+
+    writeGuidance(homes);
+
+    assert.equal(
+        readFileSync(homes.agentsPath, 'utf8'),
+        `${EXPECTED_BLOCK}\n${guidanceBlock(PACKAGE_GUIDANCE)}`,
+    );
+});
 
-    assert.equal(repaired, `${EXPECTED_BLOCK}\n${broken}`);
+test('a link to a file the package does not own is left alone', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    const ownGuidancePath = join(homes.root, 'notes', 'codex.md');
+    mkdirSync(join(homes.root, 'notes'));
+    writeFileSync(ownGuidancePath, 'My own Codex notes\n');
+    symlinkSync(ownGuidancePath, homes.agentsPath);
+
+    assert.equal(writeGuidance(homes), null);
+    assert.equal(lstatSync(homes.agentsPath).isSymbolicLink(), true);
+    assert.equal(readFileSync(ownGuidancePath, 'utf8'), 'My own Codex notes\n');
 });

package/bin/install.mjs

@@ -45,7 +45,7 @@ import {
     shouldInstallPstackPlugin,
 } from './install-pstack-plugin.mjs';
 import { seedCodexPstackModels } from './seed-codex-pstack-models.mjs';
-import { writeCodexSkillLoadBlock } from './codex-skill-load-block.mjs';
+import { writeCodexAgentsGuidance } from './codex-skill-load-block.mjs';
 import {
     continuityHostConfigurationPaths,
     removeContinuityHooks,
@@ -2788,8 +2788,10 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
                     allUserOwnedPreferencePaths.add(eachPath);
                 }
             }
-            const skillLoadGuidancePath = writeCodexSkillLoadBlock(
+            const skillLoadGuidancePath = writeCodexAgentsGuidance(
                 INSTALL_ROOT_RESOLUTION.codexHomeDirectory,
+                readFileSync(join(PACKAGE_ROOT, 'AGENTS.md'), 'utf8'),
+                [join(CLAUDE_HOME, 'AGENTS.md'), join(AGENTS_HOME, 'AGENTS.md')],
             );
             if (skillLoadGuidancePath) {
                 console.log(`  \u2713 ${skillLoadGuidancePath} (Codex skill-load line)`);

package/bin/install.test.mjs

@@ -11,6 +11,7 @@ import {
     readdirSync,
     existsSync,
     copyFileSync,
+    lstatSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
@@ -3099,6 +3100,25 @@ test('a repeat install preserves Codex pstack configuration', t => {
     assert.equal(readFileSync(join(codexHome, 'pstack-models.md'), 'utf8'), 'session hook: off\n');
 });
 
+test('a Codex guidance link to the retired Claude copy becomes a file Codex can read', t => {
+    const sandbox = pstackPluginSandbox(t);
+    const codexHome = join(sandbox.homeDirectory, '.codex');
+    const codexAgentsPath = join(codexHome, 'AGENTS.md');
+    mkdirSync(codexHome, { recursive: true });
+    symlinkSync(join(sandbox.homeDirectory, '.claude', 'AGENTS.md'), codexAgentsPath);
+
+    runPstackInstaller(sandbox.homeDirectory, [], sandbox.environment);
+
+    const packageGuidance = readFileSync(
+        join(dirname(fileURLToPath(import.meta.url)), '..', 'AGENTS.md'),
+        'utf8',
+    );
+    assert.equal(lstatSync(codexAgentsPath).isSymbolicLink(), false);
+    const codexGuidance = readFileSync(codexAgentsPath, 'utf8');
+    assert.ok(codexGuidance.startsWith(`${SKILL_LOAD_BLOCK_START}\n${SKILL_LOAD_INSTRUCTION}\n`));
+    assert.ok(codexGuidance.includes(packageGuidance));
+});
+
 test('an absent host command is reported and leaves the other host installed', t => {
     const sandbox = pstackPluginSandbox(t);
 

package/hooks/blocking/pii_prevention_blocker_parts/repository_exemption.py

@@ -64,7 +64,7 @@ def repository_allowlisted_values(repository_root: Path) -> frozenset[str]:
         The exact literal values the repository's commits and writes may carry
         past the PII scan, or an empty set when the repository has none.
     """
-    origin_slug = _repository_origin_slug(repository_root)
+    origin_slug = repository_origin_slug(repository_root)
     if origin_slug is None:
         return frozenset()
     return pii_allowlisted_values_by_repository().get(origin_slug, frozenset())
@@ -171,7 +171,7 @@ def _owner_repo_slug_from_origin_url(origin_url: str) -> str | None:
     return _owner_repo_slug_from_path(repository_path)
 
 
-def _repository_origin_slug(repository_root: Path) -> str | None:
+def repository_origin_slug(repository_root: Path) -> str | None:
     """Return the lowercased owner/repo slug of the origin remote, or None.
 
     Args:
@@ -211,7 +211,7 @@ def _is_repository_exempt_from_pii_scan(repository_root: Path) -> bool:
     Returns:
         True when the repository's origin slug is in the exempt set.
     """
-    origin_slug = _repository_origin_slug(repository_root)
+    origin_slug = repository_origin_slug(repository_root)
     if origin_slug is None:
         return False
     return origin_slug in pii_exempt_repository_slugs()

package/hooks/blocking/tests/test_repository_exemption.py

@@ -19,6 +19,7 @@ from pii_prevention_blocker_parts.repository_exemption import (
     _is_repository_exempt_from_pii_scan,
     _owner_repo_slug_from_origin_url,
     repository_allowlisted_values,
+    repository_origin_slug,
 )
 
 _ALLOWED_VALUE = "owner.fixture" + "@" + "acme-corp" + ".example" + ".io"
@@ -103,3 +104,9 @@ def test_repository_without_origin_is_never_exempt(tmp_path: Path) -> None:
 
 def test_owner_repo_slug_strips_a_trailing_slash_origin() -> None:
     assert _owner_repo_slug_from_origin_url("https://github.com/Owner/Repo/") == "owner/repo"
+
+
+def test_repository_origin_slug_reads_the_origin_remote(tmp_path: Path) -> None:
+    repository_root = tmp_path / "repo"
+    _init_repo_with_github_origin(repository_root, "SlugOwner/slug-repo")
+    assert repository_origin_slug(repository_root) == "slugowner/slug-repo"

package/package.json

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

package/rules/build-needs-a-user.md

@@ -32,7 +32,7 @@ correction arrives a second time, per
 ## Where it is enforced
 
 The staged policy lint's `uncalled-new-file` rule reads each code file a change
-adds under `scripts/`, `hooks/`, or `bin/`. It reports the file when its name
+adds under `scripts/`, `hooks/`, `bin/`, `ci/`, or `tools/`. It reports the file when its name
 appears only in its own tests, `CHANGELOG.md`, `README.md`, and
 `bin/ever-shipped-skills.mjs`. CI runs that lint against the merge base, so a
 file with no caller turns the pull request red.

package/rules/testing.md

@@ -29,4 +29,4 @@ Red, green, refactor is the default loop for a bug fix and for new behavior. The
 
 ## A Fix Carries Its Proof Test
 
-The `Fix test proof` job in `.github/workflows/pr-check.yml` runs `_shared/pr-loop/scripts/fix_pr_test_proof.py` on every pull request whose title starts with `fix`. A fix that changes production code must change at least one Python test that fails on the base and passes on the head. A fix that changes only docs or CI config passes. Version one reads Python tests only, so a fix proven by a JavaScript or PowerShell test needs a Python test beside it.
+The `Fix test proof` job in `.github/workflows/pr-check.yml` runs `_shared/pr-loop/scripts/fix_pr_test_proof.py` on every pull request whose title starts with `fix`. A fix that changes production code must change at least one Python or Node test that fails on the base and passes on the head. Node tests are files ending in `.test.mjs`, `.test.js`, or `.test.cjs`, and the job runs them with `node --test`. A fix that changes only docs or CI config passes. A fix proven by a PowerShell test needs a Python or Node test beside it.

package/scripts/policy_lint/config/constants.py

@@ -179,7 +179,7 @@ UNCALLED_NEW_FILE_MESSAGE = (
     " workflow, skill, command or import in this change, or drop it."
 )
 ALL_CALLED_CODE_SUFFIXES = frozenset({".py", ".mjs", ".js", ".sh", ".ps1"})
-ALL_CALLED_CODE_SEGMENTS = ("/scripts/", "/hooks/", "/bin/")
+ALL_CALLED_CODE_SEGMENTS = ("/scripts/", "/hooks/", "/bin/", "/ci/", "/tools/")
 ALL_CALLER_SEARCH_SKIPPED_DIRECTORIES = frozenset(
     {".git", "node_modules", "__pycache__", ".venv"}
 )

package/scripts/repository_checks/tracked_private_terms.py

@@ -13,6 +13,7 @@ from policy_lint.config import constants as policy_constants
 from private_terms import private_term_line_numbers
 
 from repository_checks.config import constants as repository_constants
+from repository_checks.hook_modules import load_hooks_module
 from repository_checks.models import RepositoryFinding
 
 
@@ -25,6 +26,15 @@ def _read_text_or_none(absolute_path: Path) -> str | None:
         return None
 
 
+def _is_owned_by_private_organization(repository_root: Path) -> bool:
+    exemption = load_hooks_module(repository_constants.REPOSITORY_EXEMPTION_MODULE_NAME)
+    origin_slug = exemption.repository_origin_slug(repository_root)
+    if origin_slug is None:
+        return False
+    owner_name = origin_slug.split(policy_constants.PATH_SEPARATOR)[0]
+    return bool(private_term_line_numbers(owner_name, ALL_PRIVATE_TERM_DIGESTS))
+
+
 def collect_tracked_private_term_findings(
     repository_root: Path, all_tracked_paths: Sequence[str]
 ) -> list[RepositoryFinding]:
@@ -35,8 +45,12 @@ def collect_tracked_private_term_findings(
         all_tracked_paths: Repository-relative tracked paths.
 
     Returns:
-        Findings that carry the path and line number, never the name.
+        Findings that carry the path and line number, never the name. A
+        repository whose github.com origin owner is itself a private
+        organization returns none, since that organization may name itself.
     """
+    if _is_owned_by_private_organization(repository_root):
+        return []
     all_findings: list[RepositoryFinding] = []
     for each_relative_path in all_tracked_paths:
         if (content := _read_text_or_none(repository_root / each_relative_path)) is None:

package/scripts/tests/test_policy_lint_rules_callers.py

@@ -124,3 +124,17 @@ def test_should_run_on_staged_and_base_selections() -> None:
     assert uncalled_rule.selections == frozenset(
         {SelectionKind.STAGED, SelectionKind.BASE}
     )
+
+
+def test_should_report_new_ci_and_tools_helpers_only_tests_name(
+    tmp_path: Path,
+) -> None:
+    ci_helper = ".github/ci/lonely_router.py"
+    tools_helper = "tools/lonely_archiver.py"
+    _write(tmp_path, ci_helper, "print('hi')\n")
+    _write(tmp_path, tools_helper, "print('hi')\n")
+    _write(tmp_path, ".github/ci/test_lonely_router.py", "import lonely_router\n")
+
+    all_messages = _messages(tmp_path, (_added(ci_helper), _added(tools_helper)))
+
+    assert len(all_messages) == 2

package/scripts/tests/test_tracked_private_terms.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import hashlib
+import subprocess
 import sys
 from pathlib import Path
 
@@ -69,3 +70,37 @@ def test_should_pass_a_tree_that_names_no_private_organization(
     exit_code, stdout_text, _stderr_text = run_policy(repository_root)
     assert exit_code == SUCCESS_EXIT_CODE
     assert stdout_text == ""
+
+
+def test_should_pass_a_repository_the_named_organization_owns(
+    tmp_path: Path,
+) -> None:
+    repository_root = tmp_path / "repo"
+    initialize_repository(repository_root)
+    subprocess.run(
+        ["git", "remote", "add", "origin", "https://github.com/AcmeWidget/app.git"],
+        cwd=repository_root,
+        check=True,
+    )
+    write_text(repository_root / "docs" / "notes.md", "Built by Acme Widgets.\n")
+    commit_tracked_files(repository_root)
+    exit_code, stdout_text, _stderr_text = run_policy(repository_root)
+    assert exit_code == SUCCESS_EXIT_CODE
+    assert stdout_text == ""
+
+
+def test_should_flag_a_repository_another_owner_holds(
+    tmp_path: Path,
+) -> None:
+    repository_root = tmp_path / "repo"
+    initialize_repository(repository_root)
+    subprocess.run(
+        ["git", "remote", "add", "origin", "https://github.com/someone/app.git"],
+        cwd=repository_root,
+        check=True,
+    )
+    write_text(repository_root / "docs" / "notes.md", "Built by Acme Widgets.\n")
+    commit_tracked_files(repository_root)
+    exit_code, stdout_text, _stderr_text = run_policy(repository_root)
+    assert exit_code == FINDINGS_EXIT_CODE
+    assert f"{CHECK_ID_TRACKED_PRIVATE_TERMS}: docs/notes.md:" in stdout_text