claude-dev-env 1.36.0 → 1.36.2

package/_shared/pr-loop/audit-contract.md

@@ -0,0 +1,159 @@
+# Audit contract
+
+Shared output schema and audit-loop contract used by `/bugteam`, `/qbug`, `/findbugs`, and `/fixbugs`. Changing a shape here is a breaking change for every consuming skill.
+
+## Contents
+
+- Finding schema (Shape A, Shape B)
+- Adversarial second pass
+- Haiku secondary auditor
+- Post-fix self-audit
+- Persistence (loop-N-audit.json, loop-N-diagnostics.json)
+
+## Finding schema
+
+Each finding an audit produces MUST be one of exactly two shapes.
+
+### Shape A — structured finding
+
+```json
+{
+  "id": "loop<N>-<K>",
+  "file": "path/relative/to/repo/root.py",
+  "line": 123,
+  "category": "A | B | C | D | E | F | G | H | I | J",
+  "severity": "P0 | P1 | P2",
+  "excerpt": "verbatim code snippet from the offending line(s)",
+  "failure_mode": "one sentence describing what goes wrong and when",
+  "evidence_files": ["additional/files/opened.py"]
+}
+```
+
+`id` is `loop<N>-<K>` where `N` is the loop counter (1-based) and `K` is the 1-based index within the loop. For `/findbugs` which runs once, use `find<K>`.
+
+### Shape B — structured proof-of-absence
+
+Used when an audit investigates a category and does NOT find a bug. Bare "verified clean" claims are REJECTED because they hide shallow reading.
+
+```json
+{
+  "category": "A | B | C | D | E | F | G | H | I | J",
+  "files_opened": ["file1.py", "file2.py"],
+  "lines_quoted": [
+    {"file": "file1.py", "line": 88, "text": "verbatim line content"}
+  ],
+  "adversarial_probes": [
+    "what failure mode was tested for and how it was ruled out"
+  ]
+}
+```
+
+Every category an audit touches MUST have either at least one Shape A finding OR at least one Shape B proof-of-absence entry. A category with neither is a protocol violation.
+
+### Example — Shape A
+
+```json
+{
+  "id": "loop1-1",
+  "file": "scripts/db/neon.py",
+  "line": 43,
+  "category": "C",
+  "severity": "P1",
+  "excerpt": "load_dotenv(env_path, override=False)",
+  "failure_mode": "Called on every connect() — repeats file I/O per connection in scripts that open multiple short-lived connections.",
+  "evidence_files": ["scripts/db/neon.py", "scripts/update_new_releases.py"]
+}
+```
+
+### Example — Shape B
+
+```json
+{
+  "category": "H",
+  "files_opened": ["scripts/db/neon.py", "scripts/db/config.py"],
+  "lines_quoted": [
+    {"file": "scripts/db/neon.py", "line": 30, "text": "dsn = os.environ.get(\"DATABASE_URL\")"}
+  ],
+  "adversarial_probes": [
+    "Checked whether DATABASE_URL is interpolated into a shell — it is passed to psycopg.connect() directly with no shell involvement.",
+    "Checked whether the env path is user-controlled — it is derived from a fixed Y: drive constant, not user input."
+  ]
+}
+```
+
+## Adversarial second pass
+
+After the primary finding list is complete, every audit runs a second pass against itself with the prompt:
+
+> Assume your first pass missed at least 3 P1 bugs. Where are they?
+
+The audit must either produce new Shape A findings citing new file:line references not present in the first pass, or cite explicit Shape B adversarial-probe entries for each category it re-examined. An adversarial pass that returns "nothing new, confident first pass was complete" is REJECTED — produce evidence or findings, not confidence.
+
+## Haiku secondary auditor
+
+For single-subagent skills (`/qbug`, `/findbugs`) the LEAD spawns two `Agent()` calls in one message:
+
+- **Primary** — `subagent_type=clean-coder`, `model=sonnet` (for qbug cycle) or `subagent_type=code-quality-agent`, `model=sonnet` (for findbugs clean-room).
+- **Secondary (Haiku)** — `subagent_type=code-quality-agent`, `model=haiku`, same self-contained clean-room prompt shape used by `/findbugs`.
+
+Both audit the same diff. The secondary returns findings to the LEAD only — never posted to the PR.
+
+Merge rules:
+
+- **De-dup key**: `(file, line, category)`.
+- **Severity conflict**: max wins (P0 > P1 > P2).
+- **Unique-to-Haiku findings**: added to the primary set with Haiku's severity and source annotation.
+- **Unique-to-primary findings**: kept as-is.
+- **Zero Haiku findings**: primary set trusted; proceed.
+- **Malformed or non-parseable Haiku output**: lead trusts the primary set, logs the event in `loop-<N>-diagnostics.json` under `haiku_findings` as `[{"parse_error": "<message>"}]`.
+
+For multi-subagent skills (`/bugteam`) the parallel-auditors pattern in [`audit-and-teammates.md`](audit-and-teammates.md) already provides cross-model coverage via the three variant teammates.
+
+## Post-fix self-audit
+
+Audit-and-fix skills (`/qbug`, `/bugteam`) MUST re-audit modified files between `py_compile` and `git add`. This catches fix-induced regressions in the same loop that introduced them rather than on loop N+1.
+
+Sequence:
+
+1. Capture pre-fix file contents for every file this FIX will touch.
+2. Apply edits.
+3. Run `py_compile` (or language-equivalent) on each modified file.
+4. Compute `fix_diff` against pre-fix contents for the modified set.
+5. Run `bugteam_code_rules_gate.py` with explicit paths for every modified file.
+6. Spawn a scoped audit of `fix_diff` with full A–J rigor, Shape A/B contract, adversarial pass, AND Haiku secondary in parallel (paranoid mode on post-fix).
+7. Any new findings become same-loop fix-targets. Internal iteration count increments by one.
+8. After 3 internal iterations with fresh findings each time, exit `stuck: post-fix audit not converging`.
+9. Only when `gate_findings` empty AND `post_fix_findings` empty: `git add`, commit, push.
+
+`converged` exit condition: `primary_audit_clean AND post_fix_audit_clean` for the committing loop.
+
+## Persistence
+
+Every audit loop writes two JSON files under the skill's scoped temp directory (resolved via `tempfile.gettempdir()`):
+
+### `loop-<N>-audit.json`
+
+```json
+{
+  "findings": [],
+  "proof_of_absence": [],
+  "source": "primary | haiku | adversarial | merged"
+}
+```
+
+### `loop-<N>-diagnostics.json`
+
+```json
+{
+  "loop": 1,
+  "gate_findings": [],
+  "primary_findings": [],
+  "adversarial_findings": [],
+  "haiku_findings": [],
+  "post_fix_findings": [],
+  "merged": [],
+  "deduped": []
+}
+```
+
+All eight keys MUST be present. Missing keys break convergence debugging.

package/_shared/pr-loop/code-rules-gate.md

@@ -0,0 +1,64 @@
+# CODE_RULES gate
+
+Pre-audit validator run before each AUDIT (and pre-commit when applicable). Wraps `validate_content` from `~/.claude/hooks/blocking/code_rules_enforcer.py`.
+
+## Script location
+
+Canonical: `~/.claude/_shared/pr-loop/scripts/code_rules_gate.py` after install.
+
+Workflows reference it via:
+- all skills (bugteam, qbug, pr-converge, monitor-many): `${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/code_rules_gate.py`
+
+Cross-skill path traversal works because every skill installs as a flat top-level dir under `~/.claude/skills/` and `_shared/` lives alongside `skills/` under `~/.claude/`.
+
+## Invocation
+
+Default mode (full PR diff against base):
+```bash
+python "<gate_script>" --base origin/<base_branch>
+```
+
+Staged mode (pre-commit subset):
+```bash
+python "<gate_script>" --staged
+```
+
+Path-scoped mode:
+```bash
+python "<gate_script>" --base origin/<base_branch> --only-under <prefix> [--only-under <other_prefix>]
+```
+
+## Exit codes
+
+- `0` — no violations on changed lines (advisories on touched-but-unchanged lines may still print)
+- `1` — at least one blocking violation on changed lines; halt
+- `2` — gate execution error (missing enforcer, git failure, malformed diff)
+
+## Workflow integration
+
+- **bugteam:** before every AUDIT in Step 3 of the loop. Non-zero → spawn clean-coder for standards fix; loop until exit 0 or 5 consecutive gate failures → `error: code rules gate failed pre-audit`.
+- **qbug:** before every AUDIT inside the subagent's loop. Three consecutive failures → `error: code rules gate failed pre-audit`.
+- **pr-converge:** before every push in the Fix protocol. Halt on non-zero, fix violations, re-run.
+- **monitor-many:** before every commit during the fix loop. Halt on non-zero, fix violations, re-run.
+
+## Coverage
+
+- File-global UPPER_SNAKE constants (must live in `config/` outside exempt path families)
+- Magic values in production function bodies (literals other than 0, 1, -1)
+- Imports outside top of module
+- New comments in production code (existing comments preserved untouched)
+- File-global constants used by fewer than 2 functions/methods
+- Logging format-arg violations
+- Database column-name string magic (snake_case strings as first element of 2-tuples in function bodies)
+- Public-wrapper-drops-optional-kwargs of same-file delegates
+
+Test files (`test_*.py`, `*_test.py`, `*.spec.*`, `conftest.py`, paths under `/tests/`) are exempt from comment, magic-value, and constants-location rules.
+
+## Halt-fix-rerun protocol
+
+When the gate exits non-zero:
+1. Capture stderr (gate prints `<file>: Line <N>: <issue>` per violation)
+2. Group violations by file
+3. Apply fixes in the smallest change set (extract constants to `config/`, rename collection params with `all_` prefix, replace literals with named constants, etc.)
+4. Re-run the gate with the same arguments
+5. Cap at 5 consecutive failures (bugteam, monitor-many) or 3 (qbug); on cap exceeded, exit `error`

package/_shared/pr-loop/fix-protocol.md

@@ -0,0 +1,37 @@
+# Fix protocol
+
+## Sequence
+
+1. **Read each referenced file:line** before editing. The repo enforces read-before-edit at the tool layer.
+2. **Capture pre-fix SHA:** `git rev-parse HEAD`. Store as `pre_fix_sha`.
+3. **Capture pre-fix file contents** for every file this fix will touch. Used in step 8 for the post-fix self-audit diff.
+4. **TDD where applicable:** when the finding has behavior to test, write a failing test first; for pure doc, comment, or naming nits with no behavior, fix directly.
+5. **Apply each fix:**
+   - Preserve existing comments on lines left unchanged
+   - Add complete type hints on every signature touched
+   - Use positive framing in any new prose (no banned negatives)
+6. **Validate each modified Python file:** `python -m py_compile <path>`. Halt on syntax error; fix and re-run.
+7. **Compute fix diff:** the diff between pre-fix and post-fix file contents for every modified file.
+8. **Post-fix self-audit:** follow [`audit-contract.md`](audit-contract.md) post-fix self-audit sequence. Internal iteration cap: 3. Three rounds with fresh findings → exit `stuck: post-fix audit not converging`. Only when `gate_findings` empty AND `post_fix_findings` empty → proceed to git add.
+9. **Stage by explicit path:** `git add <path>` for each modified file. Avoid `git add -A` and `git add .`.
+10. **Create one commit** summarizing the fixed findings. Let every git hook run. When a hook blocks the commit, capture stderr, mark every finding in this loop `status=hook_blocked`, and move to the next iteration without retrying this loop.
+11. **Push fast-forward:** `git push origin <branch>`. Verify `git fetch origin <branch> && git rev-parse origin/<branch>` matches `HEAD`.
+12. **Reply inline** on each finding's comment thread using the [`gh-payloads.md`](gh-payloads.md) reply shape. Reply body is one of:
+    - `Fixed in <short_sha>`
+    - `Could not address this loop: <one-line reason>`
+    - `Hook blocked the fix commit: <one-line summary>`
+13. **Re-trigger reviewer** when the calling workflow specifies. Workflow-specific:
+    - `pr-converge`: post `bugbot run` issue comment after every push (Cursor Bugbot)
+    - `monitor-many`: post `bugbot run` issue comment AND call `requested_reviewers` API for Copilot
+    - `bugteam` / `qbug`: skip — Claude itself is the reviewer; the next loop iteration audits
+
+## Stuck detection
+
+After step 11, when `git rev-parse HEAD` is unchanged from `pre_fix_sha`, the fix produced no commit. Exit reason: `stuck — could not address findings`. Record unresolved findings as `{file, line, severity, title, reason}` quadruples.
+
+## Constraints
+
+- Edit only files reachable from the PR diff's scope.
+- Append commits; the branch stays linear (one commit per fix loop, fast-forward push only).
+- No comment deletion on lines left unchanged.
+- No `--no-verify`. Hook rejections flag real underlying issues worth investigating.

package/_shared/pr-loop/gh-payloads.md

@@ -0,0 +1,85 @@
+# gh API payloads
+
+Shared payload shapes for posting PR reviews and replies. Used by `bugteam`, `qbug`, `pr-converge`, `monitor-many`.
+
+## Build payloads with jq + gh api --input
+
+Build JSON with `jq --rawfile` / `-Rs` reading per-finding markdown bodies from temp files; pipe to `gh api ... --input -`. Avoids shell-quoting hazards and satisfies the `gh-body-backtick-guard` hook.
+
+## One review per loop
+
+POST to `repos/<owner>/<repo>/pulls/<number>/reviews` once per audit loop. Payload: `event: "COMMENT"`, the review body, and one `comments[]` object per anchored finding.
+
+```bash
+jq -n \
+  --rawfile review_body <tmp_review_body.md> \
+  --arg commit_id "$(git rev-parse HEAD)" \
+  --rawfile finding_body_1 <tmp_finding_1.md> \
+  --arg path_1 "<file_1>" \
+  --argjson line_1 <line_1> \
+  [... one finding_body_K / path_K / line_K triple per finding ...] \
+  '{
+     commit_id: $commit_id,
+     event: "COMMENT",
+     body: $review_body,
+     comments: [
+       {path: $path_1, line: $line_1, side: "RIGHT", body: $finding_body_1}
+       [, ... ]
+     ]
+   }' \
+| gh api repos/<owner>/<repo>/pulls/<number>/reviews -X POST --input -
+```
+
+Single-line anchors: `{path, line, side: "RIGHT", body}`. Multi-line anchors add `start_line` and `start_side: "RIGHT"`.
+
+Zero findings still post one review. Body line: `## /<workflow> loop <N> audit: 0P0 / 0P1 / 0P2 → clean`. `comments: []`.
+
+## Review body template
+
+```
+## /<workflow> loop <N> audit: <P0>P0 / <P1>P1 / <P2>P2
+
+### Findings without a diff anchor
+(only when needed)
+- **[severity] title** — <file>:<line> — <one-line description>
+```
+
+`<workflow>` is the calling skill name (`bugteam`, `qbug`, `pr-converge`).
+
+## Reply to a finding
+
+POST to `repos/<owner>/<repo>/pulls/<number>/comments/<finding_comment_id>/replies`:
+
+```bash
+jq -Rs '{body: .}' <tmp_reply.md \
+| gh api repos/<owner>/<repo>/pulls/<number>/comments/<finding_comment_id>/replies -X POST --input -
+```
+
+## Anchor fallback (line not in diff)
+
+Lines not in the PR diff cannot anchor an inline comment. Omit them from `comments[]` and list under the review body's `### Findings without a diff anchor` section. Outcome record per finding: `used_fallback="true"`, empty `finding_comment_id`, `finding_comment_url` = parent review URL.
+
+## Review POST failure fallback (issue comment)
+
+When the review POST fails, post one issue comment carrying the full review body to `repos/<owner>/<repo>/issues/<number>/comments`:
+
+```bash
+jq -Rs '{body: .}' <tmp_fallback.md \
+| gh api repos/<owner>/<repo>/issues/<number>/comments -X POST --input -
+```
+
+All findings in the loop record `used_fallback="true"`; `finding_comment_url` = issue comment URL.
+
+## Endpoints
+
+- Review POST: `repos/{owner}/{repo}/pulls/{pull}/reviews`
+- Reply POST: `repos/{owner}/{repo}/pulls/{pull}/comments/{id}/replies`
+- Fallback issue comment: `repos/{owner}/{repo}/issues/{issue}/comments` (`issue` = PR number)
+
+## SHA capture timing
+
+`commit_id` and any `<head_sha_at_post_time>` reference: `git rev-parse HEAD` immediately before the POST, in the cwd of whichever subagent or process is posting.
+
+## Body file UTF-8 encoding
+
+Write each markdown body to a temp file via the BOM-free PowerShell pattern (`[IO.File]::WriteAllText($path, $content, [Text.UTF8Encoding]::new($false))`) before `gh api` consumes it. See `~/.claude/rules/gh-body-file.md`.

package/_shared/pr-loop/scripts/README.md

@@ -0,0 +1,20 @@
+# Shared PR-loop scripts
+
+Runnable helpers used by **bugteam**, **qbug**, **pr-converge**, and related skills. These files are **executed** from the repository (or a `~/.claude` install); they are not meant as primary model-reading context.
+
+## Inventory
+
+| File | Purpose |
+| --- | --- |
+| `preflight.py` | Local checks before a PR-loop run (pytest discovery, optional pre-commit, hooksPath sanity). |
+| `code_rules_gate.py` | CODE_RULES gate over PR-scoped diffs (`--base`, staged-only, path filters). |
+| `fix_hookspath.py` | Repair `core.hooksPath` when it does not point at the packaged git-hooks tree. |
+| `gh_util.py` | GitHub CLI helpers (pagination-safe JSON parsing, review fetches). |
+| `grant_project_claude_permissions.py` / `revoke_project_claude_permissions.py` | Claude Code permission JSON helpers used during publish-style flows. |
+| `_claude_permissions_common.py` | Shared implementation for the permission scripts. |
+
+Configuration lives under `config/` next to these scripts (for example `preflight_constants.py`, `code_rules_gate_constants.py`).
+
+## Gate semantics
+
+Merge-base selection, diff scoping, and exit codes for `code_rules_gate.py` are documented in [`../code-rules-gate.md`](../code-rules-gate.md).

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

@@ -0,0 +1,234 @@
+"""Shared helpers for grant_project_claude_permissions and revoke_project_claude_permissions.
+
+Writes to ~/.claude/settings.json are atomic and permission-preserving: the
+target file's existing POSIX mode is captured, a sibling temp file is
+created via os.open with O_CREAT | O_EXCL and the preserved mode, content
+is written, then os.replace swaps it into place. Output is serialized with
+sort_keys=True for a stable on-disk layout; the first run on a hand-ordered
+settings file produces a one-time re-sort diff, subsequent writes are stable.
+"""
+
+import json
+import os
+import secrets
+import stat
+import sys
+from pathlib import Path
+from typing import NoReturn
+
+sys.modules.pop("config", None)
+if str(Path(__file__).resolve().parent) not in sys.path:
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from config.claude_permissions_constants import (
+    CLAUDE_SETTINGS_DIRECTORY_NAME,
+    GIT_DIRECTORY_NAME,
+    TEXT_FILE_ENCODING as TEXT_FILE_ENCODING,
+    UNIQUE_TEMPORARY_SUFFIX_BYTE_LENGTH,
+)
+
+
+def exit_with_error(message: str) -> NoReturn:
+    print(f"Error: {message}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+def path_contains_glob_metacharacters(candidate_path: str) -> bool:
+    all_glob_metacharacters_in_path: tuple[str, ...] = (
+        "*",
+        "?",
+        "[",
+        "]",
+        "{",
+        "}",
+    )
+    return any(
+        each_character in candidate_path
+        for each_character in all_glob_metacharacters_in_path
+    )
+
+
+def get_current_project_path() -> str:
+    normalized_project_path = str(Path.cwd()).replace("\\", "/")
+    if path_contains_glob_metacharacters(normalized_project_path):
+        raise ValueError(
+            f"Current directory path contains glob metacharacters and cannot "
+            f"be used to build permission rules safely: {normalized_project_path}"
+        )
+    return normalized_project_path
+
+
+def build_permission_rule(tool_name: str, project_path: str) -> str:
+    return f"{tool_name}({project_path}/.claude/**)"
+
+
+def build_permission_rules(
+    project_path: str, all_permission_allow_tools: tuple[str, ...]
+) -> list[str]:
+    return [
+        build_permission_rule(each_tool, project_path)
+        for each_tool in all_permission_allow_tools
+    ]
+
+
+def load_settings(settings_path: Path) -> dict[str, object]:
+    if not settings_path.exists():
+        return {}
+    parsed_settings: dict[str, object] = {}
+    try:
+        raw_text = settings_path.read_text(encoding=TEXT_FILE_ENCODING)
+    except OSError as read_error:
+        exit_with_error(f"Failed to read {settings_path}: {read_error}")
+    try:
+        parsed_settings = json.loads(raw_text)
+    except json.JSONDecodeError as decode_error:
+        exit_with_error(
+            f"Refusing to modify {settings_path}: existing file is not valid JSON "
+            f"({decode_error}). Fix or back up the file manually, then re-run."
+        )
+    if not isinstance(parsed_settings, dict):
+        exit_with_error(
+            f"Refusing to modify {settings_path}: existing file's root is "
+            f"{type(parsed_settings).__name__}, not a JSON object. Fix or back up "
+            f"the file manually, then re-run."
+        )
+    return parsed_settings
+
+
+def serialize_settings_to_json_text(all_settings: dict[str, object]) -> str:
+    json_indent_width_columns: int = len("  ")
+    return json.dumps(
+        all_settings,
+        indent=json_indent_width_columns,
+        sort_keys=True,
+    )
+
+
+def get_mode_to_preserve(settings_path: Path) -> int:
+    default_settings_file_mode: int = 0o600
+    try:
+        stat_result = os.stat(settings_path)
+    except FileNotFoundError:
+        return default_settings_file_mode
+    except OSError as stat_error:
+        exit_with_error(f"Failed to stat {settings_path}: {stat_error}")
+    return stat.S_IMODE(stat_result.st_mode)
+
+
+def write_atomically_with_mode(
+    temporary_path: Path, serialized_content: str, file_mode: int
+) -> None:
+    file_descriptor = os.open(
+        str(temporary_path),
+        os.O_WRONLY | os.O_CREAT | os.O_EXCL,
+        file_mode,
+    )
+    try:
+        writer = os.fdopen(file_descriptor, "w", encoding=TEXT_FILE_ENCODING)
+    except BaseException:
+        os.close(file_descriptor)
+        raise
+    with writer:
+        writer.write(serialized_content)
+
+
+def save_settings(settings_path: Path, all_settings: dict[str, object]) -> None:
+    unique_temporary_suffix_byte_length = UNIQUE_TEMPORARY_SUFFIX_BYTE_LENGTH
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    serialized_settings = serialize_settings_to_json_text(all_settings)
+    unique_temporary_suffix = (
+        f".tmp.{os.getpid()}.{secrets.token_hex(unique_temporary_suffix_byte_length)}"
+    )
+    temporary_path = settings_path.with_suffix(
+        settings_path.suffix + unique_temporary_suffix
+    )
+    mode_to_preserve = get_mode_to_preserve(settings_path)
+    try:
+        try:
+            write_atomically_with_mode(
+                temporary_path, serialized_settings, mode_to_preserve
+            )
+            os.replace(str(temporary_path), str(settings_path))
+            os.chmod(str(settings_path), mode_to_preserve)
+        except OSError as os_error:
+            exit_with_error(
+                f"Failed to write settings atomically to {settings_path}: {os_error}"
+            )
+    finally:
+        if temporary_path.exists():
+            try:
+                temporary_path.unlink()
+            except OSError:
+                pass
+
+
+def append_if_missing(all_target_list: list[object], new_value: str) -> bool:
+    if new_value in all_target_list:
+        return False
+    all_target_list.append(new_value)
+    return True
+
+
+def ensure_dict_section(
+    all_settings: dict[str, object], section_name: str
+) -> dict[str, object]:
+    """Return an existing dict section or create an empty one if absent.
+
+    A missing key and an explicit JSON null are treated identically: both
+    produce a fresh empty dict stored back into settings. Any other non-dict
+    value (string, list, number, bool) calls exit_with_error to avoid
+    overwriting user data.
+    """
+    existing_section = all_settings.get(section_name)
+    if existing_section is None:
+        replacement_section: dict[str, object] = {}
+        all_settings[section_name] = replacement_section
+        return replacement_section
+    if not isinstance(existing_section, dict):
+        exit_with_error(
+            f"Refusing to modify settings key {section_name!r}: existing value "
+            f"is {type(existing_section).__name__}, not a JSON object. Fix or "
+            f"remove the key manually, then re-run."
+        )
+    return existing_section
+
+
+def ensure_list_entry(all_section: dict[str, object], entry_name: str) -> list[object]:
+    """Return an existing list entry or create an empty one if absent.
+
+    A missing key and an explicit JSON null are treated identically: both
+    produce a fresh empty list stored back into the section. Any other
+    non-list value (string, dict, number, bool) calls exit_with_error to
+    avoid overwriting user data.
+    """
+    existing_entry = all_section.get(entry_name)
+    if existing_entry is None:
+        replacement_entry: list[object] = []
+        all_section[entry_name] = replacement_entry
+        return replacement_entry
+    if not isinstance(existing_entry, list):
+        exit_with_error(
+            f"Refusing to modify settings entry {entry_name!r}: existing value "
+            f"is {type(existing_entry).__name__}, not a JSON array. Fix or "
+            f"remove the entry manually, then re-run."
+        )
+    return existing_entry
+
+
+def is_valid_project_root(candidate_path: Path) -> bool:
+    git_marker_path = candidate_path / GIT_DIRECTORY_NAME
+    claude_marker_path = candidate_path / CLAUDE_SETTINGS_DIRECTORY_NAME
+    return git_marker_path.exists() or claude_marker_path.exists()
+
+
+def prune_empty_list_then_empty_section(
+    all_settings: dict[str, object], section_key: str, list_key: str
+) -> None:
+    section = all_settings.get(section_key)
+    if not isinstance(section, dict):
+        return
+    list_entry = section.get(list_key)
+    if isinstance(list_entry, list) and len(list_entry) == 0:
+        del section[list_key]
+    if len(section) == 0:
+        del all_settings[section_key]