claude-dev-env 4.3.0 → 7.0.0

package/scripts/policy_lint/adapters.py

@@ -1,10 +1,13 @@
 from __future__ import annotations
 
 import importlib
+import os
 import sys
 from pathlib import Path
 from types import ModuleType
 
+from shared_tree_paths import resolve_shared_scripts_directory
+
 from . import adapter_configuration, adapter_detectors, adapter_pairing, adapter_support
 from .config import constants
 from .model import Diagnostic, Document, DocumentSet
@@ -24,10 +27,10 @@ def _hooks_module(module_name: str) -> ModuleType:
 
 
 def _pr_loop_script_module(module_name: str) -> ModuleType:
-    package_directory = Path(__file__).resolve().parent.parent.parent
-    scripts_directory = str(
-        package_directory.joinpath(*constants.ALL_PR_LOOP_SCRIPTS_PATH_SEGMENTS)
-    )
+    scripts_directory = str(resolve_shared_scripts_directory(
+        __file__, os.environ, constants.PR_LOOP_DIRECTORY_NAME,
+        f"{module_name}{constants.PYTHON_SUFFIX}", constants.SHARED_ROOT_PARENT_INDEX
+    ))
     if scripts_directory not in sys.path:
         sys.path.insert(0, scripts_directory)
     return importlib.import_module(module_name)

package/scripts/policy_lint/config/constants.py

@@ -5,6 +5,7 @@ INVALID_INPUT_EXIT_CODE = 2
 GIT_EXECUTABLE = "git"
 UTF8_ENCODING = "utf-8"
 PATH_SEPARATOR = "/"
+ARCHIVED_SKILLS_DIRECTORY_NAME = "skill-archive"
 NUL_BYTE = b"\0"
 ALL_GIT_ROOT_ARGUMENTS = ("rev-parse", "--show-toplevel")
 ALL_GIT_HEAD_ARGUMENTS = ("rev-parse", "--verify", "HEAD")
@@ -13,6 +14,7 @@ GIT_MERGE_BASE_ARGUMENT = "merge-base"
 GIT_HEAD_REFERENCE = "HEAD"
 GIT_INDEX_REFERENCE_PREFIX = ""
 GIT_ENVIRONMENT_VARIABLE_PREFIX = "GIT_"
+GIT_INDEX_ENVIRONMENT_VARIABLE = "GIT_INDEX_FILE"
 ALL_GIT_BLOB_ARGUMENTS = ("cat-file", "blob")
 ALL_MISSING_BLOB_ERROR_FRAGMENTS = (
     "does not exist in",
@@ -75,3 +77,6 @@ TERMINOLOGY_FINDING_PATTERN = re.compile(
 TERMINOLOGY_PATH_GROUP = "path"
 TERMINOLOGY_LINE_NUMBER_GROUP = "line_number"
 TERMINOLOGY_MESSAGE_GROUP = "message"
+
+PR_LOOP_DIRECTORY_NAME = "pr-loop"
+SHARED_ROOT_PARENT_INDEX = 2

package/scripts/policy_lint/engine.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
 from collections.abc import Iterable, Sequence
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 
+from .config.constants import ARCHIVED_SKILLS_DIRECTORY_NAME
 from .model import (
     ChangeSetRule,
     Diagnostic,
@@ -25,6 +26,9 @@ def lint(
 ) -> LintReport:
     """Run the selected rules on one source selection.
 
+    Repository and diff selections check active code. File and editor
+    selections include archived skills.
+
     Args:
         request: Repository root, source, and rule sets.
         all_registry: Optional registry replacement.
@@ -32,10 +36,14 @@ def lint(
     Returns:
         A report of diagnostics and rule execution state.
     """
-    document_set = select_documents(request)
-    candidate_rules = tuple(all_registry) if all_registry is not None else default_registry()
+    document_set = _runtime_document_set(select_documents(request))
+    candidate_rules = (
+        tuple(all_registry) if all_registry is not None else default_registry()
+    )
     selected = selected_rules(candidate_rules, request.rule_sets)
-    all_diagnostics, executed, failed, skipped = _run_selected_rules(selected, document_set)
+    all_diagnostics, executed, failed, skipped = _run_selected_rules(
+        selected, document_set
+    )
     return LintReport(
         1,
         tuple(sorted(all_diagnostics, key=_diagnostic_sort_key)),
@@ -46,6 +54,42 @@ def lint(
     )
 
 
+def _is_runtime_path(path: PurePosixPath) -> bool:
+    return path.parts[0] != ARCHIVED_SKILLS_DIRECTORY_NAME
+
+
+def _runtime_document_set(document_set: DocumentSet) -> DocumentSet:
+    if document_set.selection in {SelectionKind.FILES, SelectionKind.TEXT}:
+        return document_set
+    all_documents = tuple(
+        each_document
+        for each_document in document_set.documents
+        if _is_runtime_path(each_document.path)
+    )
+    all_deleted_paths = tuple(
+        each_path
+        for each_path in document_set.deleted_paths
+        if _is_runtime_path(each_path)
+    ) + tuple(
+        old_path
+        for old_path, new_path in document_set.renamed_paths
+        if _is_runtime_path(old_path) and not _is_runtime_path(new_path)
+    )
+    all_renamed_paths = tuple(
+        each_pair
+        for each_pair in document_set.renamed_paths
+        if _is_runtime_path(each_pair[1])
+    )
+    return DocumentSet(
+        all_documents,
+        document_set.selection,
+        document_set.repository_root,
+        all_deleted_paths,
+        all_renamed_paths,
+        document_set.base_revision,
+    )
+
+
 def _run_selected_rules(
     all_rules: tuple[Rule, ...], document_set: DocumentSet
 ) -> tuple[list[Diagnostic], tuple[str, ...], tuple[str, ...], tuple[str, ...]]:

package/scripts/policy_lint/model.py

@@ -106,6 +106,7 @@ class DocumentSet:
     repository_root: Path
     deleted_paths: tuple[PurePosixPath, ...] = ()
     renamed_paths: tuple[tuple[PurePosixPath, PurePosixPath], ...] = ()
+    base_revision: str | None = None
 
 
 @dataclass(frozen=True)

package/scripts/policy_lint/registry.py

@@ -141,7 +141,7 @@ def default_registry() -> tuple[model.Rule, ...]:
         model.ChangeSetRule(
             "terminology-sweep",
             frozenset({"changed"}),
-            frozenset({model.SelectionKind.STAGED}),
+            frozenset({model.SelectionKind.STAGED, model.SelectionKind.BASE}),
             adapters.terminology_diagnostics,
         ),
         model.RepositoryRule(

package/scripts/policy_lint/selection.py

@@ -172,7 +172,7 @@ def _documents_from_changes(
     selection_kind = SelectionKind.STAGED if is_staged else SelectionKind.BASE
     return DocumentSet(
         tuple(all_documents), selection_kind, repository_root,
-        tuple(all_deleted_paths), tuple(all_renamed_paths),
+        tuple(all_deleted_paths), tuple(all_renamed_paths), base_revision,
     )
 
 
@@ -354,6 +354,7 @@ def _normalize_document_set(repository_root: Path, document_set: DocumentSet) ->
         repository_root,
         all_deleted_paths,
         all_renamed_paths,
+        document_set.base_revision,
     )
 
 

package/scripts/policy_lint/selection_git.py

@@ -10,6 +10,7 @@ from .config.constants import (
     ALL_MISSING_BLOB_ERROR_FRAGMENTS,
     ALL_UNBORN_HEAD_ERROR_FRAGMENTS,
     GIT_ENVIRONMENT_VARIABLE_PREFIX,
+    GIT_INDEX_ENVIRONMENT_VARIABLE,
     GIT_EXECUTABLE,
     NUL_BYTE,
     UTF8_ENCODING,
@@ -105,6 +106,7 @@ def _git_subprocess_environment() -> dict[str, str]:
         each_name: each_environment_text
         for each_name, each_environment_text in os.environ.items()
         if not each_name.upper().startswith(git_prefix)
+        or each_name.upper() == GIT_INDEX_ENVIRONMENT_VARIABLE
     }
 
 

package/scripts/refresh_pstack_plugin_skills.mjs

@@ -0,0 +1,200 @@
+/**
+ * Keep a pstack skills-directory plugin manifest listing every skill folder.
+ *
+ * Claude Code loads a folder under `~/.claude/skills` as a plugin when the
+ * folder holds `.claude-plugin/plugin.json`, and it namespaces that plugin's
+ * skills as `pstack:how`. It does not scan a plugin root for skill folders, so
+ * the manifest names each sub-skill path:
+ *
+ *     plugin root holds: how/SKILL.md, why/SKILL.md, docs/, .claude-plugin/
+ *     manifest before:   "skills": ["./how"]
+ *     manifest after:    "skills": ["./how", "./why"]   <- why/ picked up
+ *     second run:        no write                        <- the list matches
+ *     docs/, .claude-plugin/                             <- skipped, no SKILL.md
+ *
+ * The installer calls `refreshPstackPluginManifest` for a pstack folder the
+ * user installed. Running this file directly refreshes the same manifest after
+ * a pstack update.
+ */
+
+import {
+    existsSync,
+    mkdirSync,
+    readdirSync,
+    readFileSync,
+    realpathSync,
+    writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const PSTACK_PLUGIN_DIRECTORY_NAME = 'pstack';
+export const PSTACK_PLUGIN_MANIFEST_RELATIVE_PATH = join('.claude-plugin', 'plugin.json');
+export const SKILL_MANIFEST_FILE_NAME = 'SKILL.md';
+export const SKILL_PATH_PREFIX = './';
+
+const CLAUDE_HOME_DIRECTORY_NAME = '.claude';
+const MANIFEST_SKILLS_KEY = 'skills';
+const MANIFEST_INDENT_SPACES = 2;
+const FILE_ENCODING = 'utf8';
+const HIDDEN_NAME_PREFIX = '.';
+
+/**
+ * Fields a first write seeds from the published pstack plugin. An existing
+ * manifest keeps its own values. This refresher changes only the skills list.
+ */
+const SEEDED_MANIFEST_FIELDS = Object.freeze({
+    $schema: 'https://anthropic.com/claude-code/plugin.schema.json',
+    name: PSTACK_PLUGIN_DIRECTORY_NAME,
+    version: '0.14.8',
+    description:
+        'if you want to go fast, go deep first. pstack helps you write less, but higher '
+        + 'quality code. rigorous agent workflows you can parallelize with confidence.',
+    author: Object.freeze({ name: 'Lauren Tan' }),
+    homepage: 'https://github.com/cursor/plugins/tree/main/pstack',
+    repository: 'https://github.com/cursor/plugins',
+    license: 'MIT',
+});
+
+/**
+ * Name every sub-folder of a plugin root that Claude Code loads as a skill.
+ *
+ * @param {string} pluginRoot Plugin folder holding one sub-folder per skill.
+ * @returns {string[]} The sorted names of each visible sub-folder holding a
+ *   skill manifest. A hidden folder and a folder without `SKILL.md` are left out.
+ */
+export function findPstackSkillDirectoryNames(pluginRoot) {
+    return readdirSync(pluginRoot, { withFileTypes: true })
+        .filter((eachEntry) => eachEntry.isDirectory())
+        .map((eachEntry) => eachEntry.name)
+        .filter((eachName) => !eachName.startsWith(HIDDEN_NAME_PREFIX))
+        .filter((eachName) => existsSync(join(pluginRoot, eachName, SKILL_MANIFEST_FILE_NAME)))
+        .sort();
+}
+
+function readManifestSkillPaths(manifestPath) {
+    if (!existsSync(manifestPath)) return { manifest: null, previousSkillPaths: [] };
+    const manifest = JSON.parse(readFileSync(manifestPath, FILE_ENCODING));
+    const listedSkillPaths = manifest[MANIFEST_SKILLS_KEY];
+    if (typeof listedSkillPaths === 'string') {
+        return { manifest, previousSkillPaths: [listedSkillPaths] };
+    }
+    if (Array.isArray(listedSkillPaths)) {
+        return { manifest, previousSkillPaths: listedSkillPaths };
+    }
+    return { manifest, previousSkillPaths: [] };
+}
+
+/**
+ * Rewrite a pstack plugin manifest's skills list to match its folder.
+ *
+ * Writes only when the list changes. A second call on an unchanged folder
+ * leaves the file byte for byte. An existing manifest keeps every field but
+ * the skills list.
+ *
+ * @param {string} pluginRoot Plugin folder holding the skill sub-folders.
+ * @returns {{didWrite: boolean, reason: string, previousSkillPaths: string[],
+ *   currentSkillPaths: string[]}} Whether this call wrote, and the paths
+ *   before and after. `reason` names a skip, and is empty on a write or an
+ *   unchanged list.
+ */
+export function refreshPstackPluginManifest(pluginRoot) {
+    const declined = { didWrite: false, previousSkillPaths: [], currentSkillPaths: [] };
+    if (!existsSync(pluginRoot)) {
+        return { ...declined, reason: 'plugin root is absent' };
+    }
+    if (existsSync(join(pluginRoot, SKILL_MANIFEST_FILE_NAME))) {
+        return { ...declined, reason: 'plugin root is itself a skill' };
+    }
+    const allSkillNames = findPstackSkillDirectoryNames(pluginRoot);
+    if (allSkillNames.length === 0) {
+        return { ...declined, reason: 'plugin root holds no skills' };
+    }
+    const manifestPath = join(pluginRoot, PSTACK_PLUGIN_MANIFEST_RELATIVE_PATH);
+    const { manifest, previousSkillPaths } = readManifestSkillPaths(manifestPath);
+    const currentSkillPaths = allSkillNames.map((eachName) => SKILL_PATH_PREFIX + eachName);
+    const outcome = { reason: '', previousSkillPaths, currentSkillPaths };
+    const isUnchanged = manifest !== null
+        && previousSkillPaths.length === currentSkillPaths.length
+        && previousSkillPaths.every((eachPath, eachIndex) => eachPath === currentSkillPaths[eachIndex]);
+    if (isUnchanged) {
+        return { ...outcome, didWrite: false };
+    }
+    const refreshedManifest = {
+        ...(manifest === null ? SEEDED_MANIFEST_FIELDS : manifest),
+        [MANIFEST_SKILLS_KEY]: currentSkillPaths,
+    };
+    mkdirSync(join(pluginRoot, '.claude-plugin'), { recursive: true });
+    writeFileSync(
+        manifestPath,
+        JSON.stringify(refreshedManifest, null, MANIFEST_INDENT_SPACES) + '\n',
+        FILE_ENCODING,
+    );
+    return { ...outcome, didWrite: true };
+}
+
+/**
+ * Return the pstack plugin folder under a Claude home.
+ *
+ * @param {string} claudeHome The Claude home directory holding `skills`.
+ * @returns {string} The pstack plugin folder path, present or not.
+ */
+export function pstackPluginRootFor(claudeHome) {
+    return join(claudeHome, 'skills', PSTACK_PLUGIN_DIRECTORY_NAME);
+}
+
+/**
+ * Return the Claude home used when no folder argument is given.
+ *
+ * A named profile sets `CLAUDE_CONFIG_DIR`. The installer writes into that
+ * root. The command-line form reads the same variable.
+ *
+ * @param {Record<string, string|undefined>} environment The process environment.
+ * @returns {string} The Claude home directory holding `skills`.
+ */
+export function claudeHomeFrom(environment) {
+    return environment.CLAUDE_CONFIG_DIR || join(homedir(), CLAUDE_HOME_DIRECTORY_NAME);
+}
+
+function main() {
+    const explicitRoot = process.argv[2];
+    const pluginRoot = explicitRoot || pstackPluginRootFor(claudeHomeFrom(process.env));
+    const outcome = refreshPstackPluginManifest(pluginRoot);
+    if (!outcome.didWrite && outcome.reason) {
+        console.log(`No manifest written: ${outcome.reason}.`);
+        return;
+    }
+    if (!outcome.didWrite) {
+        console.log(`No change. ${outcome.currentSkillPaths.length} skills listed.`);
+        return;
+    }
+    console.log(`Updated. ${outcome.currentSkillPaths.length} skills listed.`);
+    for (const eachPath of outcome.currentSkillPaths) {
+        if (!outcome.previousSkillPaths.includes(eachPath)) console.log(`  added   ${eachPath}`);
+    }
+    for (const eachPath of outcome.previousSkillPaths) {
+        if (!outcome.currentSkillPaths.includes(eachPath)) console.log(`  removed ${eachPath}`);
+    }
+}
+
+/**
+ * Return whether node ran this module as its entry point.
+ *
+ * A directory link to this script gives node an invoked path that differs from
+ * this module's own path. Both sides resolve to their real location before
+ * the comparison.
+ *
+ * @param {string|undefined} invokedPath The path node reports as `argv[1]`.
+ * @returns {boolean} True when node ran this module as its entry point.
+ */
+function isEntryPoint(invokedPath) {
+    if (!invokedPath) return false;
+    try {
+        return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(invokedPath);
+    } catch {
+        return fileURLToPath(import.meta.url) === invokedPath;
+    }
+}
+
+if (isEntryPoint(process.argv[1])) main();

package/scripts/shared_tree_paths.py

@@ -11,7 +11,9 @@ from collections.abc import Mapping
 from pathlib import Path
 
 from dev_env_scripts_constants.shared_tree_constants import (
+    AGENTS_DIRECTORY_SUFFIX,
     CLAUDE_CONFIG_DIR_ENV_VAR,
+    DEFAULT_MANAGED_ROOT_NAME,
     PROCESS_TREE_DIRECTORY_NAME,
     PROCESS_TREE_KILL_MODULE_FILENAME,
     SCRIPTS_DIRECTORY_NAME,
@@ -29,6 +31,29 @@ def _shared_scripts_directory(from_root: Path, shared_subpackage_name: str) -> P
     )
 
 
+def _linked_managed_root(module_path: Path, anchor_depth: int) -> Path | None:
+    """Resolve the managed root whose scripts pointer targets this installed tree.
+
+    Args:
+        module_path: The module path inside the managed scripts tree.
+        anchor_depth: Parent index of the package or agents root.
+
+    Returns:
+        The Claude managed root when its scripts pointer resolves to this tree.
+    """
+    package_root = module_path.resolve().parents[anchor_depth]
+    if not package_root.name.endswith(AGENTS_DIRECTORY_SUFFIX):
+        return None
+    managed_name = package_root.name.removesuffix(AGENTS_DIRECTORY_SUFFIX) or DEFAULT_MANAGED_ROOT_NAME
+    managed_root = package_root.parent / managed_name
+    linked_scripts = managed_root / SCRIPTS_DIRECTORY_NAME
+    if not linked_scripts.is_dir():
+        return None
+    if linked_scripts.resolve() != package_root / SCRIPTS_DIRECTORY_NAME:
+        return None
+    return managed_root
+
+
 def resolve_shared_scripts_directory(
     module_file: str | Path,
     all_environment: Mapping[str, str],
@@ -44,9 +69,10 @@ def resolve_shared_scripts_directory(
         ok:   an un-resolved parent keeps the link side, where _shared sits
         flag: a resolved parent walks the link and misses _shared entirely
 
-    Tries the un-resolved parent first, then the configured managed root,
-    then the resolved parent. When none holds the marker, returns the
-    un-resolved candidate, so an import failure names a readable path.
+    Tries the un-resolved parent first, then a verified installed scripts
+    pointer, then the configured managed root, then the resolved parent.
+    If none holds the marker, returns the un-resolved candidate so an
+    import failure names a readable path.
 
     Args:
         module_file: Path of the importing module (``__file__``).
@@ -63,6 +89,9 @@ def resolve_shared_scripts_directory(
         module_path.absolute().parents[anchor_depth], shared_subpackage_name
     )
     all_candidates = [un_resolved_candidate]
+    linked_root = _linked_managed_root(module_path, anchor_depth)
+    if linked_root is not None:
+        all_candidates.append(_shared_scripts_directory(linked_root, shared_subpackage_name))
     configured_root_text = all_environment.get(CLAUDE_CONFIG_DIR_ENV_VAR, "").strip()
     if configured_root_text:
         all_candidates.append(

package/scripts/test_shared_tree_paths.py

@@ -171,3 +171,36 @@ def test_generalized_resolver_serves_a_deeper_anchor(tmp_path: Path) -> None:
         3,
     )
     assert resolved_scripts_directory == expected_scripts_directory
+
+
+@pytest.mark.parametrize("managed_name", (".claude", "profile-a"))
+def test_resolved_agents_scripts_find_the_verified_managed_root(
+    tmp_path: Path, managed_name: str,
+) -> None:
+    agents_name = ".agents" if managed_name == ".claude" else f"{managed_name}.agents"
+    agents_root = tmp_path / agents_name
+    scripts_directory = agents_root / "scripts"
+    scripts_directory.mkdir(parents=True)
+    module_file = scripts_directory / "runner.py"
+    module_file.write_text("", encoding="utf-8")
+    managed_root = tmp_path / managed_name
+    managed_root.mkdir()
+    _create_directory_link(from_link=managed_root / "scripts", to_target=scripts_directory)
+    expected = _write_process_tree_kill_stub(managed_root)
+    resolved_directory = shared_tree_paths.resolve_shared_process_tree_scripts_directory(module_file, {})
+    assert resolved_directory == expected
+
+
+def test_neighboring_managed_root_cannot_supply_a_foreign_shared_tree(tmp_path: Path) -> None:
+    agents_root = tmp_path / ".agents"
+    scripts_directory = agents_root / "scripts"
+    scripts_directory.mkdir(parents=True)
+    module_file = scripts_directory / "runner.py"
+    module_file.write_text("", encoding="utf-8")
+    managed_root = tmp_path / ".claude"
+    foreign_scripts = managed_root / "scripts"
+    foreign_scripts.mkdir(parents=True)
+    _write_process_tree_kill_stub(managed_root)
+    resolved_directory = shared_tree_paths.resolve_shared_process_tree_scripts_directory(module_file, {})
+    expected = agents_root / "_shared" / "process-tree" / "scripts"
+    assert resolved_directory == expected

package/scripts/tests/test_policy_lint_rules_archive.py

@@ -0,0 +1,120 @@
+"""Archive boundaries for automatic and explicitly requested policy checks."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path, PurePosixPath
+
+import pytest
+from policy_lint.engine import _runtime_document_set, lint
+from policy_lint.model import (
+    Diagnostic,
+    Document,
+    DocumentRule,
+    DocumentSet,
+    LintRequest,
+    Location,
+    SelectionKind,
+    Severity,
+    TextDocument,
+)
+
+
+def _git(repository_root: Path, *arguments: str) -> None:
+    environment = {
+        variable_name: variable_text
+        for variable_name, variable_text in os.environ.items()
+        if not variable_name.upper().startswith("GIT_")
+    }
+    subprocess.run(
+        ["git", *arguments], cwd=repository_root, env=environment,
+        check=True, capture_output=True, text=True,
+    )
+
+
+@pytest.fixture
+def archive_repository(tmp_path: Path) -> Path:
+    _git(tmp_path, "init", "--quiet", "-b", "main")
+    _git(tmp_path, "config", "user.name", "Archive Tests")
+    _git(tmp_path, "config", "user.email", "archive@example.invalid")
+    _git(tmp_path, "config", "commit.gpgsign", "false")
+    for relative_path in ("active.py", "skill-archive/old.py", "src/skill-archive/live.py"):
+        file_path = tmp_path / relative_path
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_text("first\n", encoding="utf-8")
+    _git(tmp_path, "add", ".")
+    _git(tmp_path, "commit", "--quiet", "-m", "archive fixture")
+    for file_path in tmp_path.rglob("*.py"):
+        file_path.write_text("second\n", encoding="utf-8")
+    _git(tmp_path, "add", ".")
+    return tmp_path
+
+
+def _marker_diagnostics(document: Document, repository_root: Path) -> tuple[Diagnostic, ...]:
+    assert (repository_root / document.path).is_file()
+    return (Diagnostic("marker", Severity.ERROR, "Checked document", Location(document.path, 1)),)
+
+
+def _accept_document(document: Document) -> bool:
+    return bool(document.path.parts)
+
+
+def _marker_rule() -> DocumentRule:
+    return DocumentRule(
+        "marker", frozenset({"changed", "repository"}),
+        _accept_document, _marker_diagnostics,
+    )
+
+
+@pytest.mark.parametrize("selection", (SelectionKind.STAGED, SelectionKind.BASE, SelectionKind.REPOSITORY))
+def test_automatic_checks_keep_live_code_and_exclude_only_root_archive(
+    archive_repository: Path, selection: SelectionKind,
+) -> None:
+    requests = {
+        SelectionKind.STAGED: LintRequest.staged(archive_repository),
+        SelectionKind.BASE: LintRequest.base(archive_repository, "HEAD"),
+        SelectionKind.REPOSITORY: LintRequest.repository(archive_repository),
+    }
+    report = lint(requests[selection], all_registry=(_marker_rule(),))
+    assert report.checked_documents == (
+        PurePosixPath("active.py"), PurePosixPath("src/skill-archive/live.py"),
+    )
+    assert len(report.diagnostics) == 2
+    assert report.executed_rules == ("marker",)
+    assert report.exit_code == 1
+
+
+@pytest.mark.parametrize("selection", (SelectionKind.FILES, SelectionKind.TEXT))
+def test_explicit_archive_checks_still_execute_rules(
+    archive_repository: Path, selection: SelectionKind,
+) -> None:
+    archive_path = Path("skill-archive/old.py")
+    request = (
+        LintRequest.files(archive_repository, [archive_path])
+        if selection is SelectionKind.FILES
+        else LintRequest(archive_repository, TextDocument(archive_path, "editor text\n"))
+    )
+    report = lint(request, all_registry=(_marker_rule(),))
+    assert report.checked_documents == (PurePosixPath("skill-archive/old.py"),)
+    assert len(report.diagnostics) == 1
+    assert report.exit_code == 1
+
+
+def test_retirement_and_restoration_preserve_live_change_metadata(tmp_path: Path) -> None:
+    retired_path = PurePosixPath("active/retired.py")
+    archive_path = PurePosixPath("skill-archive/retired.py")
+    restored_source = PurePosixPath("skill-archive/restored.py")
+    restored_path = PurePosixPath("active/restored.py")
+    deleted_path = PurePosixPath("active/deleted.py")
+    document_set = DocumentSet(
+        (Document.from_text(archive_path, "archived"), Document.from_text(restored_path, "restored")),
+        SelectionKind.BASE,
+        tmp_path,
+        (deleted_path, PurePosixPath("skill-archive/deleted.py")),
+        ((retired_path, archive_path), (restored_source, restored_path)),
+    )
+    runtime_set = _runtime_document_set(document_set)
+    assert tuple(document.path for document in runtime_set.documents) == (restored_path,)
+    assert runtime_set.deleted_paths == (deleted_path, retired_path)
+    assert runtime_set.renamed_paths == ((restored_source, restored_path),)

package/scripts/tests/test_policy_lint_rules_engine.py

@@ -10,7 +10,7 @@ from pathlib import Path, PurePosixPath
 import pytest
 from policy_lint import adapters
 from policy_lint.config.constants import INCOMPLETE_EXIT_CODE
-from policy_lint.engine import lint
+from policy_lint.engine import _runtime_document_set, lint
 from policy_lint.model import (
     ContentOrigin,
     Diagnostic,
@@ -309,7 +309,11 @@ def test_state_description_diagnostics_maps_and_scopes_phrases(
     lint_report = _lint_documents(
         tmp_path,
         (source_document,),
-        (_changed_document_rule("state-description", adapters.state_description_diagnostics),),
+        (
+            _changed_document_rule(
+                "state-description", adapters.state_description_diagnostics
+            ),
+        ),
     )
     assert len(lint_report.diagnostics) == 1
     assert lint_report.diagnostics[0].location is not None
@@ -351,8 +355,12 @@ def test_failed_adapter_rolls_back_continues_and_exits_incomplete(
         _source_document("pkg/second.py"),
     )
     all_rules = (
-        _changed_document_rule("flaky", lambda document, _root: _flaky_diagnostics(document)),
-        _changed_document_rule("stable", lambda document, _root: _stable_diagnostics(document)),
+        _changed_document_rule(
+            "flaky", lambda document, _root: _flaky_diagnostics(document)
+        ),
+        _changed_document_rule(
+            "stable", lambda document, _root: _stable_diagnostics(document)
+        ),
     )
     lint_report = _lint_documents(repository_root, all_documents, all_rules)
     assert lint_report.failed_rules == ("flaky",)
@@ -379,3 +387,16 @@ def test_process_interrupt_is_not_swallowed(tmp_path: Path) -> None:
             (_source_document("pkg/mod.py"),),
             (_changed_document_rule("interrupt", interrupt_diagnostics),),
         )
+
+
+def test_runtime_document_set_keeps_base_revision_for_base_selection(
+    tmp_path: Path,
+) -> None:
+    document_set = DocumentSet(
+        (_source_document("pkg/mod.py"),),
+        SelectionKind.BASE,
+        tmp_path,
+        base_revision="abc123def",
+    )
+    runtime_document_set = _runtime_document_set(document_set)
+    assert runtime_document_set.base_revision == "abc123def"