claude-dev-env 4.1.0 → 4.3.0

package/.agents/skills/everything-search/SKILL.md

@@ -13,13 +13,23 @@ Search files instantly on Windows using the Everything command-line interface (e
 
 ## Hard limits
 
-Every search carries a scope: a project path or registry token, an `ext:` filter, a `dm:` date filter, a `size:` filter, or a name pattern. A bare whole-drive scan or a network-share sweep is out of bounds — narrow the search to what you need.
+Every search carries a scope: a project path or registry token, an `ext:` filter, a `dm:` date filter, a `size:` filter, or a name pattern. A bare whole-drive scan or a network-share sweep is out of bounds. Narrow the search to what you need.
 
 When `es.exe` fails or returns nothing, self-heal first: fall back to the `Glob` tool (name and path patterns) or `Grep` (file contents), and report the outage so the reader knows the index was unavailable. When self-healing also fails, ask the user through `AskUserQuestion` with a short analysis and next-step options.
 
 ## Registry tokens
 
-The `es_exe_path_rewriter` hook resolves scope tokens before the command runs. A `{project-name}` placeholder or a bare registry key from `~/.claude/project-paths.json` becomes its quoted absolute path in the command. The hook allows and rewrites — it never blocks — so a search scoped to a registered project names the project token and lets the hook fill in the path.
+Run project-name searches through this command:
+
+```text
+python "${CLAUDE_SKILL_DIR}/scripts/everything_search.py" <project-name> <search arguments>
+```
+
+The command reads `~/.claude/project-paths.json`. An exact project name or `{project-name}` argument becomes one absolute path. Unknown names, absolute paths, flags, and spaces stay as they are. The command then starts `es.exe` without a shell.
+
+Put the search scope first. The first argument names a project, path, file, extension, date, or size. An options-only request exits before `es.exe` starts. Use `-version` alone to read the installed Everything version.
+
+Path and operator searches run when the registry file is missing. Malformed registry content, an empty search, a missing `es.exe`, or a process start failure returns a nonzero exit. After a successful start, the command returns the `es.exe` exit status.
 
 ## Instructions
 
@@ -131,7 +141,7 @@ Run separate searches for each extension type:
 
 - Everything must be running (system tray) for es.exe to work
 - Run one extension per search for cleaner results
-- Use `dm:` for recent file searches instead of manual date filtering
+- Use `dm:` to filter recent files by the index timestamp
 - Combine with path to narrow scope
 - Results return instantly regardless of drive size
 
@@ -152,3 +162,8 @@ Everything indexes REAL paths only, not junctions or mapped drives.
 **Common drive mappings:**
 - `Z:\Projects\` -> `Y:\Work\Projects\`
 - When in Z:\, translate to Y:\ equivalent for Everything searches
+
+## Files
+
+- `scripts/everything_search.py` runs one Everything search without a shell.
+- `scripts/test_everything_search.py` verifies registry expansion and command failures.

package/.agents/skills/everything-search/scripts/everything_search.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from collections.abc import Mapping, Sequence
+from pathlib import Path, PurePosixPath, PureWindowsPath
+from typing import TextIO
+
+from everything_search_command_constants.config.constants import (
+    CLAUDE_DIRECTORY_NAME,
+    EXECUTABLE_NAME,
+    EXECUTION_ERROR_EXIT_CODE,
+    INFORMATIONAL_ARGUMENT,
+    INVALID_INPUT_EXIT_CODE,
+    PROJECT_PATHS_FILE_NAME,
+    REGISTRY_META_KEY,
+    SEARCH_SCOPE_REQUIRED_MESSAGE,
+    UTF8_ENCODING,
+)
+
+
+class RegistryRunFatal(ValueError):
+    """Stop the run when the project-path registry is unreadable or invalid."""
+
+
+def load_registry(registry_path: Path) -> dict[str, str]:
+    """Read project names and absolute paths from a registry file.
+
+    Args:
+        registry_path: Registry file to read.
+
+    Returns:
+        The registered paths keyed by project name.
+
+    Raises:
+        RegistryRunFatal: The file is unreadable or its content is invalid.
+    """
+    if not registry_path.is_file():
+        return {}
+    try:
+        all_registry_entries = json.loads(
+            registry_path.read_text(encoding=UTF8_ENCODING)
+        )
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise RegistryRunFatal(f"Malformed registry: {error}") from error
+    return _validated_registry_entries(all_registry_entries)
+
+
+def _validated_registry_entries(all_registry_entries: object) -> dict[str, str]:
+    if not isinstance(all_registry_entries, dict):
+        raise RegistryRunFatal("Invalid registry: expected an object")
+    all_registered_paths_by_name: dict[str, str] = {}
+    for each_registry_name, each_registered_path in all_registry_entries.items():
+        if each_registry_name == REGISTRY_META_KEY:
+            continue
+        if not isinstance(each_registry_name, str) or not isinstance(
+            each_registered_path, str
+        ):
+            raise RegistryRunFatal("Invalid registry: names and paths must be strings")
+        if not _is_absolute_path(each_registered_path):
+            raise RegistryRunFatal("Invalid registry: paths must be absolute")
+        all_registered_paths_by_name[each_registry_name] = each_registered_path
+    return all_registered_paths_by_name
+
+
+def _is_absolute_path(search_argument: str) -> bool:
+    try:
+        return (
+            PureWindowsPath(search_argument).is_absolute()
+            or PurePosixPath(search_argument).is_absolute()
+        )
+    except ValueError:
+        return False
+
+
+def _registry_name(search_argument: str) -> str:
+    if search_argument.startswith("{") and search_argument.endswith("}"):
+        return search_argument[1:-1]
+    return search_argument
+
+
+def expand_search_arguments(
+    all_search_arguments: Sequence[str],
+    all_registered_paths_by_name: Mapping[str, str],
+) -> list[str]:
+    """Return the registered path for an exact project name or `{project-name}` token.
+
+    Unknown names, absolute paths, flags, and spaces stay as their own arguments.
+
+    Args:
+        all_search_arguments: Everything search arguments.
+        all_registered_paths_by_name: Absolute paths keyed by project name.
+
+    Returns:
+        Arguments with exact project names as their registered paths.
+    """
+    all_expanded_arguments: list[str] = []
+    for each_search_argument in all_search_arguments:
+        registry_name = _registry_name(each_search_argument)
+        if (
+            not _is_absolute_path(each_search_argument)
+            and registry_name in all_registered_paths_by_name
+        ):
+            all_expanded_arguments.append(all_registered_paths_by_name[registry_name])
+        else:
+            all_expanded_arguments.append(each_search_argument)
+    return all_expanded_arguments
+
+
+def _run_search(
+    executable_path: str,
+    all_search_arguments: Sequence[str],
+    search_stdout: TextIO,
+    search_stderr: TextIO,
+) -> int:
+    try:
+        search_run = subprocess.run(
+            [executable_path, *all_search_arguments],
+            capture_output=True,
+            check=False,
+            encoding=UTF8_ENCODING,
+            shell=False,
+            text=True,
+        )
+    except OSError as error:
+        search_stderr.write(f"{error}\n")
+        return EXECUTION_ERROR_EXIT_CODE
+    search_stdout.write(search_run.stdout)
+    search_stderr.write(search_run.stderr)
+    return search_run.returncode
+
+
+def _run_registered_search(
+    all_search_arguments: Sequence[str],
+    registry_path: Path,
+    executable_path: str | None,
+    search_stdout: TextIO,
+    search_stderr: TextIO,
+) -> int:
+    try:
+        all_registered_paths_by_name = load_registry(registry_path)
+    except RegistryRunFatal as error:
+        search_stderr.write(f"{error}\n")
+        return INVALID_INPUT_EXIT_CODE
+    selected_executable_path = executable_path or shutil.which(EXECUTABLE_NAME)
+    if selected_executable_path is None:
+        search_stderr.write(f"{EXECUTABLE_NAME} was not found.\n")
+        return EXECUTION_ERROR_EXIT_CODE
+    all_expanded_arguments = expand_search_arguments(
+        all_search_arguments, all_registered_paths_by_name
+    )
+    return _run_search(
+        selected_executable_path,
+        all_expanded_arguments,
+        search_stdout,
+        search_stderr,
+    )
+
+
+def _has_search_scope(all_search_arguments: Sequence[str]) -> bool:
+    first_argument = all_search_arguments[0]
+    return bool(first_argument.strip()) and not first_argument.startswith("-")
+
+
+def _is_informational_operation(all_search_arguments: Sequence[str]) -> bool:
+    return (
+        len(all_search_arguments) == 1
+        and all_search_arguments[0].casefold() == INFORMATIONAL_ARGUMENT
+    )
+
+
+def main(all_search_arguments: Sequence[str]) -> int:
+    """Expand project names and run one Everything search.
+
+    Args:
+        all_search_arguments: Arguments passed to Everything.
+
+    Returns:
+        The Everything process exit status or a command error status.
+    """
+    if not all_search_arguments:
+        sys.stderr.write("At least one search argument is required.\n")
+        return INVALID_INPUT_EXIT_CODE
+    if not _has_search_scope(all_search_arguments) and not _is_informational_operation(
+        all_search_arguments
+    ):
+        sys.stderr.write(SEARCH_SCOPE_REQUIRED_MESSAGE)
+        return INVALID_INPUT_EXIT_CODE
+    selected_registry_path = (
+        Path.home() / CLAUDE_DIRECTORY_NAME / PROJECT_PATHS_FILE_NAME
+    )
+    return _run_registered_search(
+        all_search_arguments,
+        selected_registry_path,
+        None,
+        sys.stdout,
+        sys.stderr,
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/.agents/skills/everything-search/scripts/everything_search_command_constants/__init__.py

@@ -0,0 +1 @@
+"""Constants for the Everything search command."""

package/.agents/skills/everything-search/scripts/everything_search_command_constants/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration for the Everything search command."""

package/.agents/skills/everything-search/scripts/everything_search_command_constants/config/constants.py

@@ -0,0 +1,11 @@
+"""Configuration constants for the Everything search command."""
+
+CLAUDE_DIRECTORY_NAME = ".claude"
+EXECUTABLE_NAME = "es.exe"
+EXECUTION_ERROR_EXIT_CODE = 1
+INFORMATIONAL_ARGUMENT = "-version"
+INVALID_INPUT_EXIT_CODE = 2
+PROJECT_PATHS_FILE_NAME = "project-paths.json"
+REGISTRY_META_KEY = "_meta"
+SEARCH_SCOPE_REQUIRED_MESSAGE = "The first search argument must define a path, project, name, extension, date, or size scope.\n"
+UTF8_ENCODING = "utf-8"

package/.agents/skills/everything-search/scripts/test_everything_search.py

@@ -0,0 +1,172 @@
+import importlib
+import io
+import json
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+if str(SCRIPTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIRECTORY))
+
+search = importlib.import_module("everything_search")
+
+KNOWN_PATH = "Y:\\Projects\\my-repo"
+REGISTRY = {"my-repo": KNOWN_PATH}
+
+
+def test_expand_search_arguments_rewrites_bare_registry_token() -> None:
+    assert search.expand_search_arguments(["my-repo", "config.py"], REGISTRY) == [
+        KNOWN_PATH,
+        "config.py",
+    ]
+
+
+def test_expand_search_arguments_rewrites_exact_placeholder_token() -> None:
+    assert search.expand_search_arguments(["{my-repo}", "config.py"], REGISTRY) == [
+        KNOWN_PATH,
+        "config.py",
+    ]
+
+
+def test_expand_search_arguments_preserves_unknown_tokens_and_spaces() -> None:
+    all_arguments = ["unknown-name", "foo bar", "config.py"]
+    assert search.expand_search_arguments(all_arguments, REGISTRY) == all_arguments
+
+
+@pytest.mark.parametrize(
+    "absolute_path",
+    [
+        "C:/Users/example/file.py",
+        "\\\\server\\share\\folder",
+        "/mnt/c/Projects/repo",
+    ],
+)
+def test_expand_search_arguments_preserves_absolute_paths(absolute_path: str) -> None:
+    assert search.expand_search_arguments([absolute_path], REGISTRY) == [absolute_path]
+
+
+def test_expand_search_arguments_preserves_embedded_flag_tokens() -> None:
+    all_arguments = ["--flag={my-repo}", "--regex=^{my-repo}$"]
+    assert search.expand_search_arguments(all_arguments, REGISTRY) == all_arguments
+
+
+def test_load_registry_returns_empty_mapping_for_missing_file(tmp_path: Path) -> None:
+    assert search.load_registry(tmp_path / "missing.json") == {}
+
+
+@pytest.mark.parametrize(
+    "registry_bytes",
+    [
+        b"\xff",
+        b"{not valid",
+        json.dumps({"my-repo": 42}).encode(),
+        json.dumps({"my-repo": ""}).encode(),
+        json.dumps({"my-repo": "relative/path"}).encode(),
+    ],
+)
+def test_load_registry_reports_invalid_input(
+    tmp_path: Path, registry_bytes: bytes
+) -> None:
+    registry_path = tmp_path / "project-paths.json"
+    registry_path.write_bytes(registry_bytes)
+    with pytest.raises(search.RegistryRunFatal, match="(Malformed|Invalid)"):
+        search.load_registry(registry_path)
+
+
+def test_main_runs_direct_search_without_registry_or_shell() -> None:
+    completed_process = search.subprocess.CompletedProcess(
+        args=["es.exe", "foo bar"],
+        returncode=0,
+        stdout="found path\n",
+        stderr="",
+    )
+    captured_stdout = io.StringIO()
+    with (
+        patch.object(search, "load_registry", return_value={}),
+        patch.object(search.shutil, "which", return_value="es.exe"),
+        patch.object(
+            search.subprocess, "run", return_value=completed_process
+        ) as run_process,
+        patch.object(search.sys, "stdout", captured_stdout),
+    ):
+        exit_code = search.main(["foo bar"])
+    assert exit_code == 0
+    assert captured_stdout.getvalue() == "found path\n"
+    run_process.assert_called_once_with(
+        ["es.exe", "foo bar"],
+        capture_output=True,
+        check=False,
+        encoding="utf-8",
+        shell=False,
+        text=True,
+    )
+
+
+def test_main_passes_through_child_exit_status() -> None:
+    completed_process = search.subprocess.CompletedProcess(
+        args=["es.exe", "config.py"], returncode=7, stdout="", stderr="failed\n"
+    )
+    captured_stderr = io.StringIO()
+    with (
+        patch.object(search, "load_registry", return_value={}),
+        patch.object(search.shutil, "which", return_value="es.exe"),
+        patch.object(search.subprocess, "run", return_value=completed_process),
+        patch.object(search.sys, "stderr", captured_stderr),
+    ):
+        exit_code = search.main(["config.py"])
+    assert exit_code == 7
+    assert captured_stderr.getvalue() == "failed\n"
+
+
+def test_main_reports_missing_executable() -> None:
+    captured_stderr = io.StringIO()
+    with (
+        patch.object(search, "load_registry", return_value={}),
+        patch.object(search.shutil, "which", return_value=None),
+        patch.object(search.sys, "stderr", captured_stderr),
+    ):
+        exit_code = search.main(["config.py"])
+    assert exit_code != 0
+    assert "es.exe" in captured_stderr.getvalue()
+
+
+def test_main_reports_empty_search_arguments() -> None:
+    captured_stderr = io.StringIO()
+    with patch.object(search.sys, "stderr", captured_stderr):
+        exit_code = search.main([])
+    assert exit_code == search.INVALID_INPUT_EXIT_CODE
+    assert "search argument" in captured_stderr.getvalue()
+
+
+@pytest.mark.parametrize("all_arguments", [["-n", "50"], [""], ["   "]])
+def test_main_rejects_unscoped_search_without_launching_child(
+    all_arguments: list[str],
+) -> None:
+    captured_stderr = io.StringIO()
+    with (
+        patch.object(search.subprocess, "run") as run_process,
+        patch.object(search.sys, "stderr", captured_stderr),
+    ):
+        exit_code = search.main(all_arguments)
+    assert exit_code == search.INVALID_INPUT_EXIT_CODE
+    assert "first search argument" in captured_stderr.getvalue().lower()
+    run_process.assert_not_called()
+
+
+def test_main_allows_version_information_operation() -> None:
+    completed_process = search.subprocess.CompletedProcess(
+        args=["es.exe", "-version"], returncode=0, stdout="1.1.0.30\n", stderr=""
+    )
+    with (
+        patch.object(search, "load_registry", return_value={}),
+        patch.object(search.shutil, "which", return_value="es.exe"),
+        patch.object(
+            search.subprocess, "run", return_value=completed_process
+        ) as run_process,
+    ):
+        exit_code = search.main(["-version"])
+    assert exit_code == 0
+    run_process.assert_called_once()

package/.agents/skills/issue-tracker/SKILL.md

@@ -60,6 +60,12 @@ Search open and closed issues on the target repo before create. Open twin -> upd
 
 Prefer GitHub MCP. Fall back to `gh` on the same REST endpoints. Full map and `.id` rule: [reference/operation-matrix.md](reference/operation-matrix.md).
 
+Before issue creation, a full issue body edit, or an issue comment, write the
+body to a UTF-8 file and run
+`../_shared/pr-loop/scripts/durable_post_lint.py`. Use `issue-create`,
+`issue-edit`, or `issue-comment` as the action. Send the server write only
+after exit code `0`.
+
 ## Handoff input
 
 Optional issue-candidate JSON from orchestrator or closeout. Full schema and consume path: [reference/handoff-schema.md](reference/handoff-schema.md).

package/.agents/skills/pull-request/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: pull-request
+description: >-
+  Validate and publish GitHub pull request actions. Triggers: create PR, open
+  pull request, edit PR, update PR body, comment on PR, review PR, publish a
+  draft PR, scoped GitHub author.
+---
+
+# Pull request
+
+## Contents
+
+- [Principle](#principle)
+- [When this applies](#when-this-applies)
+- [Constraints](#constraints)
+- [Dependencies](#dependencies)
+- [Sub-skills](#sub-skills)
+- [Task seeding](#task-seeding)
+- [Process](#process)
+- [Exit handling](#exit-handling)
+- [Examples](#examples)
+- [Gotchas](#gotchas)
+- [File index](#file-index)
+- [Folder map](#folder-map)
+
+## Principle
+
+Publish one GitHub pull request action from validated local files and a
+process-local author value. Keep the parent environment unchanged.
+
+## When this applies
+
+Use this skill for one pull request action:
+
+- Create a draft pull request.
+- Edit a pull request title or body.
+- Add a pull request comment.
+- Submit a pull request review.
+- Recover one selected legacy author record before the action.
+
+Send issue create, edit, and comment work to `issue-tracker`. Send review
+convergence to `pr-cleanup` or `autoconverge`. Send commits to
+`source-command-commit`.
+
+Require one repository and one action target. Stop before author lookup or
+network work when the repository, pull request, action, author, or required
+local file is missing or ambiguous.
+
+Use these exact refusal responses when the request belongs to another skill:
+
+- Issue action: `Use issue-tracker for this GitHub issue action.`
+- Commit or push: `Use source-command-commit for this commit or push.`
+- Missing target: `Provide one repository and one pull request action target.`
+
+## Constraints
+
+- Run local validation and privacy checks before account lookup or network work.
+- Use a body file. Do not send inline body text through the shell.
+- Keep `GITHUB_DEFAULT_ACCOUNT`, the parent environment, and global GitHub CLI
+  state unchanged.
+- Run one create, edit, comment, review, or recovery action per command.
+- Use global account switching only for one explicitly selected legacy record.
+- Read back the remote state before reporting success.
+
+## Dependencies
+
+The commands use Python 3.11 or later and the Python standard library. GitHub
+actions also require an authenticated `gh` executable. The linter and artifact
+uploader ship in this package. Set `GITHUB_DEFAULT_ACCOUNT` to one exact GitHub
+CLI login when the action needs a selected author. Leave it unset to use the
+current process environment.
+
+## Sub-skills
+
+| Skill | When | Produces | If missing |
+|---|---|---|---|
+| `pr-description-writer` | Before create or a full body rewrite | A reviewed title and body file | Stop the create or rewrite and report that authoring is required |
+| `pr-title-description` | Optional title and body review | Review findings for the writer's output | Continue with the required writer output |
+| `privacy-hygiene` | Before any durable GitHub post | A clean body and repository privacy sweep | Stop before publication and report the missing gate |
+| `issue-tracker` | Issue create, edit, or comment requests | Issue state and issue URLs | Route the request there. |
+| `pr-cleanup` | Placement, naming, sizing, or cleanup convergence | Cleanup findings or a focused PR boundary | Route the request there. |
+| `autoconverge` | Autonomous PR review and fix loops | A converged draft or ready-state decision | Route the request there. |
+| `source-command-commit` | Commit or push requests | A verified commit or pushed branch | Route the request there. |
+
+## Task seeding
+
+At the start of the work, register every item in
+`reference/publication-tasks.md` through `TaskCreate`, `TodoWrite`, or the host
+task equivalent when one is available. If no task tool is available, use the
+catalog and the running work ledger. Mark each task with `PASS`, `FAIL` plus
+file and line evidence, or `N/A` plus a reason for a conditional task.
+
+## Process
+
+### 1. Scope the action
+
+Resolve the repository, action, and selected GitHub author. For create, resolve
+the source branch, base, and head. For other actions, resolve one existing pull
+request target. Create actions publish drafts. Record the target before any write.
+
+### 2. Author the title and body
+
+For create and full body rewrite, invoke the installed
+`pr-description-writer`. Require its title and body file as the authoring
+output. `pr-title-description` may review that output. A comment or review may
+use a supplied body file when it does not rewrite the pull request description.
+
+### 3. Run the local linter
+
+Run `_shared/pr-loop/scripts/durable_post_lint.py` with the matching action and
+title or body file. Use `pr-create`, `pr-edit`, `pr-comment`, or `pr-review`.
+The linter owns the action-specific body, title, and volatile-path rules.
+
+Exit code `0` continues to the next gate. Any non-zero exit stops the action. Fix
+the named local input and rerun the linter. Do not look up the author or make a
+network call while validation fails.
+
+### 4. Run privacy and artifact checks
+
+Invoke `privacy-hygiene` before the GitHub post. Upload binary evidence with
+`scripts/gh_artifact_upload.py` and replace local artifact references with
+permanent URLs. Rerun the linter after changing the body.
+
+### 5. Resolve the process-local author
+
+Run `.agents/skills/pull-request/scripts/pull_request.py` with one structured
+action and the selected author. The command runs the linter again, resolves
+the author value, and passes it only to the child `gh` process. It never
+changes the parent environment or calls `gh auth switch`.
+
+If the selected author has no usable value, stop and report the account lookup
+failure. Never print the value.
+
+### 6. Recover a selected legacy record
+
+Run `.agents/skills/pull-request/scripts/recover_legacy_author.py
+<exact-state-file> --confirm-inactive` only when the user selects one legacy
+state file. The command checks the record's age, secure file metadata, and
+contents. The confirmation flag records that the caller verified inactivity.
+Leave every other record untouched. Delete the selected record only after a
+successful restore. Mark this step `N/A` when no legacy state file is selected.
+
+### 7. Run the action
+
+Run `pull_request.py` for exactly one of `create`, `edit`, `comment`, or
+`review`. Supply the validated body file path. Treat a non-zero exit as a
+failed publication and preserve the local inputs for retry.
+
+### 8. Read back the remote state
+
+Use the same selected process-local author for a read-only remote readback.
+Confirm the pull request URL and number, title, body, head SHA, and draft state.
+For comments and reviews, confirm the new remote entry. Report artifact URLs
+without exposing author values.
+
+## Exit handling
+
+Stop before network work when authoring, local validation, privacy, or author
+selection fails. A failed action preserves its body and any recovery record.
+Report the generic error and the next required input. A successful action ends
+only after remote readback proves the requested state.
+
+## Examples
+
+Create example: the writer produces `pr-body.md`. The linter exits `0` for
+`pr-create`. `pull_request.py create` publishes one draft pull request. The
+readback matches the title, body, head SHA, and draft state.
+
+Rejected comment example: the comment body names a worktree file. The linter
+returns a non-zero exit. No account lookup or GitHub request runs. Replace the
+path with inline text or a permanent artifact URL, then rerun.
+
+Recovery example: one old record remains after an interrupted legacy account
+swap. The user selects that exact file and confirms its session is inactive.
+The recovery command restores the named account and deletes only that record.
+
+## Gotchas
+
+- Relative body-file paths depend on the caller directory. Use an absolute path
+  when another process or worktree starts the command.
+- A record older than 30 minutes can still belong to a live session. Require
+  `--confirm-inactive` before recovery.
+- Normal pull request actions never call `gh auth switch`. If that command
+  appears outside explicit recovery, stop.
+- GitHub CLI output can contain account data. The command captures account
+  lookup and recovery output and prints only generic errors.
+
+## File index
+
+| Path | Purpose |
+|---|---|
+| `SKILL.md` | Hub for pull request publication, validation, author selection, recovery, and readback |
+| `reference/publication-tasks.md` | Ordered tasks for every publication gate |
+| `scripts/pull_request.py` | Command for author selection and create, edit, comment, and review actions |
+| `scripts/github_pr_command_constants/` | Constants for pull request actions, recovery, exit codes, and generic messages |
+| `scripts/test_pull_request.py` | Tests for `pull_request.py` |
+| `scripts/recover_legacy_author.py` | Command for one selected legacy author record |
+| `scripts/test_github_pr_command_constants.py` | Tests for the command and recovery constants |
+| `scripts/test_recover_legacy_author.py` | Tests for `recover_legacy_author.py` |
+| `_shared/pr-loop/scripts/durable_post_lint.py` | Shared action-aware title, body, and path validator |
+| `_shared/pr-loop/scripts/test_durable_post_lint.py` | Tests for the shared validator |
+| `scripts/gh_artifact_upload.py` | Helper for permanent GitHub binary evidence URLs |
+| `scripts/tests/test_gh_artifact_upload.py` | Tests for binary evidence upload |
+
+## Folder map
+
+```text
+pull-request/
+├── SKILL.md
+├── reference/
+│   └── publication-tasks.md
+└── scripts/
+    ├── pull_request.py
+    ├── github_pr_command_constants/
+    ├── recover_legacy_author.py
+    ├── test_pull_request.py
+    └── test_recover_legacy_author.py
+```