claude-dev-env 2.31.1 → 2.33.0

package/scripts/test_shared_tree_paths.py

@@ -141,3 +141,33 @@ def test_missing_module_returns_unresolved_candidate(tmp_path: Path) -> None:
     assert not (
         expected_scripts_directory / PROCESS_TREE_KILL_MODULE_FILENAME
     ).is_file()
+
+
+def test_generalized_resolver_serves_a_deeper_anchor(tmp_path: Path) -> None:
+    """A caller three levels under the root resolves its own sub-package.
+
+    This is the shape the pr-loop and codex-review scripts carry, which the
+    process-tree wrapper's own anchor of one level cannot reach.
+    """
+    installed_root = tmp_path / "root"
+    module_directory = installed_root / "_shared" / "pr-loop" / "scripts"
+    module_directory.mkdir(parents=True)
+    module_file = str(module_directory / "run_codex_review.py")
+    expected_scripts_directory = (
+        installed_root
+        / SHARED_PACKAGE_DIRECTORY_NAME
+        / PROCESS_TREE_DIRECTORY_NAME
+        / SCRIPTS_DIRECTORY_NAME
+    )
+    expected_scripts_directory.mkdir(parents=True)
+    (expected_scripts_directory / PROCESS_TREE_KILL_MODULE_FILENAME).write_text(
+        "", encoding="utf-8"
+    )
+    resolved_scripts_directory = shared_tree_paths.resolve_shared_scripts_directory(
+        module_file,
+        {},
+        PROCESS_TREE_DIRECTORY_NAME,
+        PROCESS_TREE_KILL_MODULE_FILENAME,
+        3,
+    )
+    assert resolved_scripts_directory == expected_scripts_directory

package/scripts/tests/test_rules.py

@@ -76,3 +76,114 @@ def test_every_shipped_claude_rule_maps_to_an_mdc() -> None:
         if each_rule_file.name in _SKIPPED_RULE_FILE_NAMES:
             continue
         assert each_rule_file.name in output_name_by_rule_file, each_rule_file.name
+
+
+def _comment_policy_phrases() -> tuple[str, ...]:
+    return (
+        "when a change touches code that an existing comment describes or is attached to",
+        "leave comments tied to untouched code unchanged",
+        "keep comment cleanup inside the requested task",
+        "production and tests follow one rule",
+        "changed directive, todo, fixme, hack, xxx, and type-ignore comments are removed rather than added or justified",
+    )
+
+
+def _comment_policy_surfaces(package_root: Path) -> tuple[Path, ...]:
+    return (
+        package_root.parent.parent / "AGENTS.md",
+        package_root / "AGENTS.md",
+        package_root / "docs" / "CODE_RULES.md",
+        package_root / "system-prompts" / "software-engineer.xml",
+        package_root / ".agents" / "agents" / "clean-coder.md",
+        package_root / ".agents" / "agents" / "code-quality-agent.md",
+        package_root / "_shared" / "pr-loop" / "code-rules-gate.md",
+        package_root / "audit-rubrics" / "category_rubrics" / "category-j-code-rules-compliance.md",
+        package_root / "audit-rubrics" / "prompts" / "category-j-code-rules-compliance.md",
+        package_root / "audit-rubrics" / "category_rubrics" / "category-l-behavior-equivalence.md",
+        package_root / "audit-rubrics" / "prompts" / "category-l-behavior-equivalence.md",
+        package_root / ".agents" / "skills" / "grok-spawn" / "reference" / "worker-briefs.md",
+        package_root.parent.parent / ".github" / "copilot-instructions.md",
+    )
+
+
+def _worker_policy_phrases() -> tuple[str, ...]:
+    return (
+        "do not add code comments.",
+        "preserve existing comments.",
+        "docstrings remain allowed.",
+    )
+
+
+def _worker_policy_surfaces(package_root: Path) -> tuple[Path, ...]:
+    return (
+        package_root.parent.parent / "AGENTS.md",
+        package_root / "AGENTS.md",
+        package_root / "docs" / "CODE_RULES.md",
+        package_root / "system-prompts" / "software-engineer.xml",
+        package_root / ".agents" / "agents" / "clean-coder.md",
+        package_root / ".agents" / "skills" / "grok-spawn" / "reference" / "worker-briefs.md",
+        package_root.parent.parent / ".github" / "copilot-instructions.md",
+    )
+
+
+def test_comment_guidance_reaches_installed_instruction_surfaces() -> None:
+    expected_phrases = _comment_policy_phrases()
+    all_surface_paths = _comment_policy_surfaces(_PACKAGE_ROOT)
+
+    for each_surface_path in all_surface_paths:
+        surface_text = each_surface_path.read_text(encoding="utf-8").lower()
+        for each_phrase in expected_phrases:
+            assert each_phrase in surface_text, each_surface_path
+    for each_surface_path in _worker_policy_surfaces(_PACKAGE_ROOT):
+        surface_text = each_surface_path.read_text(encoding="utf-8").lower()
+        for each_phrase in _worker_policy_phrases():
+            assert each_phrase in surface_text, each_surface_path
+
+
+def _category_l_policy_texts() -> tuple[str, str, str]:
+    category_l_rubric = (
+        _PACKAGE_ROOT
+        / "audit-rubrics"
+        / "category_rubrics"
+        / "category-l-behavior-equivalence.md"
+    )
+    category_l_prompt = (
+        _PACKAGE_ROOT
+        / "audit-rubrics"
+        / "prompts"
+        / "category-l-behavior-equivalence.md"
+    )
+    audit_categories = _PACKAGE_ROOT / "audit-rubrics" / "audit-categories.json"
+    return tuple(
+        each_path.read_text(encoding="utf-8").lower()
+        for each_path in (category_l_rubric, category_l_prompt, audit_categories)
+    )
+
+
+def _comment_policy_summary_texts() -> tuple[str, str, str, str]:
+    clean_coder = _PACKAGE_ROOT / ".agents" / "agents" / "clean-coder.md"
+    category_j = (
+        _PACKAGE_ROOT
+        / "audit-rubrics"
+        / "category_rubrics"
+        / "category-j-code-rules-compliance.md"
+    )
+    code_quality = _PACKAGE_ROOT / ".agents" / "agents" / "code-quality-agent.md"
+    gate = _PACKAGE_ROOT / "_shared" / "pr-loop" / "code-rules-gate.md"
+    return tuple(
+        each_path.read_text(encoding="utf-8").lower()
+        for each_path in (clean_coder, category_j, code_quality, gate)
+    )
+
+
+def test_comment_policy_uses_changed_comment_names_and_type_directives() -> None:
+    category_l_rubric, category_l_prompt, audit_categories = _category_l_policy_texts()
+    clean_coder, category_j, code_quality, gate = _comment_policy_summary_texts()
+    assert "| l7 | changed-comment handling" in category_l_rubric
+    assert "**l7. changed-comment handling**" in category_l_prompt
+    assert '"axis_name": "changed-comment handling"' in audit_categories
+    assert "no type-ignore directives" in clean_coder
+    assert "no `# type: ignore` directives" in category_j
+    assert "production and test code" in code_quality
+    assert "comments tied to touched code are removed" in gate
+    assert "comments tied to untouched code remain unchanged" in gate

package/system-prompts/software-engineer.xml

@@ -115,8 +115,7 @@
   Types — complete coverage required:
   - Every parameter and return value carries an explicit type hint
   - Replace Any with the most specific type available
-  - Prefer a real type over `# type: ignore`; when an ignore is required, add a second
-    trailing `#` justification of at least five characters (AGENTS Types)
+  - Avoid `# type: ignore`; remove it and use a typed boundary or real type (AGENTS Types)
 
   Configuration — one source of truth:
   - Every constant lives in config/ only
@@ -124,10 +123,12 @@
   - UPPER_SNAKE names belong in config/ only
 
   Comments — preservation, add-time blocking:
-  - Keep every comment on an untouched line untouched; removing one prints a stderr advisory and lets the edit through
-  - Adding a new inline comment in production code blocks the edit
+  - Preserve existing comments.
+  - Do not add code comments.
+  - When a change touches code that an existing comment describes or is attached to, remove that comment in the same change and carry its meaning through clear names and structure. Leave comments tied to untouched code unchanged. Keep comment cleanup inside the requested task.
+  - Production and tests follow one rule. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed rather than added or justified.
   - Express new explanations through self-documenting names
-  - Docstrings on new files, methods, and classes are permitted
+  - Docstrings remain allowed.
 
   Style — enforced at write time:
   - Imports belong at the top of the file
@@ -197,11 +198,6 @@
 </scope_discipline>
 
 <git_workflow>
-  Maintain one commit per review stage. The initial feature is one commit. Each subsequent
-  review round adds exactly one commit. Each round's fixes belong in a single, dedicated
-  commit; keep the initial feature commit and each review-fix commit separate to preserve
-  the full review history.
-
   Keep working documents and image files out of the repository. Files matching these patterns
   belong outside the repo:
   - docs/plans/*.md — working planning documents
@@ -212,13 +208,6 @@
   When multiple features need shared infrastructure, extract the shared infrastructure into
   its own PR, get it reviewed and merged, then launch parallel feature PRs that import it.
 
-  When running as a GitHub Action (detected via the GITHUB_ACTIONS=true environment variable),
-  commit and push each logical change as it completes rather than batching the full session
-  into a single commit at the end. Each incremental commit carries a focused message
-  describing only that change. This gives PR observers real-time progress and lets them
-  intervene mid-run. The "one commit per review stage" rule above applies to interactive
-  local sessions; in the GitHub Actions context the entire run is the review stage, and
-  incremental commits within it are the expected shape.
 </git_workflow>
 
 <agent_workflow>
@@ -251,8 +240,6 @@
 
   Reply to each comment inline on the PR after the fix is in place.
 
-  Produce one review-fix commit per review round. Each round gets exactly one commit covering
-  all fixes for that round.
 </code_review_response>
 
 <documentation>

package/.agents/skills-archived/split-pr/SKILL.md

@@ -1,85 +0,0 @@
----
-name: split-pr
-description: >-
-  Source-owned PR analyzer for the hand-written line metric and 200/600 split
-  gates. Triggers: /split-pr analyze, split analysis, hand-written lines,
-  200/600 PR split.
----
-
-# split-pr (analyzer)
-
-**Source-owned analyzer** for the locked hand-written line metric and the 200 /
-600 split gates. Reports hand-written churn separately from excluded churn
-(generated, vendor, minified, lockfile). File count informs judgment and is
-never a hard gate.
-
-## Gotchas
-
-- **Hand-written lines are additions plus deletions** on non-excluded paths.
-- **200 hand-written lines** require a recorded `split_analysis` document.
-- **600 hand-written lines** default to multiple PR slices (`default_split`).
-- **Atomic exception** at 600+ needs a recorded unsplittable reason and a
-  standing Fable verdict token — never stay one PR silently.
-- **File count is context only.** It never blocks analysis.
-
-## When this applies
-
-- User asks for a split analysis or hand-written line report on a PR or file list.
-- A PR approaches or exceeds the 200 / 600 hand-written line surfaces.
-
-## Process
-
-1. Run `python scripts/analyze_pr.py --files-json <path> --pretty` (or `--pr N`).
-2. Read `hand_written_lines`, `excluded_churn_lines`, `requires_split_analysis`,
-   `default_split`, and optional `atomic_exception`.
-3. At 200+ without a prior analysis artifact, record the analyzer JSON before
-   shipping further commits on that surface.
-4. At 600+ with `default_split=true`, plan multiple PR slices unless
-   `atomic_exception` carries a Fable-approved reason.
-
-## File index
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Analyzer contract and 200/600 gates |
-| `scripts/analyze_pr.py` | Emit analysis JSON from gh or offline files |
-| `scripts/categorize_files.py` | Path churn class (hand-written vs excluded) |
-| `scripts/split_pr_script_types.py` | Canonical split-plan build and path-assignment validation |
-| `scripts/split_pr_title.py` | Collapse titles to exactly one conventional prefix |
-| `scripts/split_pr_layer_order.py` | Deterministic config→other layer sort |
-| `scripts/split_pr_paginate.py` | Paginated PR file intake via gh api --slurp |
-| `scripts/pack_files_into_slices.py` | Pack annotated files into ≤200 hand-written-line slices by layer |
-| `scripts/config/packing_constants.py` | Review budget, hard cap, path→layer markers for packing |
-| `scripts/test_categorize_files_packing.py` | Budget packing and layer inference tests |
-| `scripts/verify_plan.py` | Coverage verification: unique path assignment, path normalization, title contract |
-| `scripts/test_verify_plan.py` | Full-coverage and gap rejection tests |
-| `scripts/test_verify_plan_contract.py` | source_commit and title-normalization contract tests |
-| `scripts/test_verify_plan_path_normalization.py` | Unsafe-path fail-closed tests |
-| `scripts/split_pr_dependency_graph.py` | Deterministic layer-rank dependency graph over slices |
-| `scripts/config/dependency_constants.py` | Graph key names and layer ranks |
-| `scripts/test_split_pr_dependency_graph.py` | Graph order, duplicate-id, unknown-layer tests |
-| `scripts/verify_dependency_graph.py` | CLI + shape/order checks for a dependency graph document |
-| `scripts/test_verify_dependency_graph.py` | Rebuild-order accept/reject and CLI exit tests |
-| `scripts/config/split_pr_constants.py` | Thresholds and excluded path markers |
-| `scripts/config/plan_constants.py` | Plan schema keys, layer order, title-prefix tokens |
-| `scripts/test_analyze_pr.py` | Boundary tests at 199/200/599/600 |
-| `scripts/test_categorize_files.py` | Exclusion classification tests |
-| `scripts/test_split_pr_script_types.py` | Plan schema and full path assignment |
-| `scripts/test_split_pr_title.py` | One-prefix title normalization |
-| `scripts/test_split_pr_layer_order.py` | Layer order ranking |
-| `scripts/test_split_pr_paginate.py` | Slurp page flattening |
-| `scripts/split_pr_process_runner.py` | Captured subprocess runner for Git ops |
-| `scripts/split_pr_git_operations.py` | Safe local slice commit + restore via git_operations_constants |
-| `scripts/execute_split_slices.py` | Materialize full plan in topo order |
-| `scripts/config/git_operations_constants.py` | Git argv tokens and error strings |
-| `scripts/test_split_pr_git_operations.py` | Dirty-tree, path staging, restore tests |
-| `scripts/test_execute_split_slices.py` | Plan walk order and failure restore |
-| `reference/proposal-format.md` | Human-readable plan field contract |
-| `reference/splitting-principles.md` | Vertical-slice invariants |
-| `reference/path-layers.md` | Layer hints (context only) |
-| `reference/split-further-loop.md` | Re-split loop until leaves fit review |
-
-## Folder map
-
-- `scripts/` — analyzer, categorize helpers, plan verifier, plan contract, constants, tests
-- `reference/` — vertical-slice principles, layer hints, plan field contract

package/.agents/skills-archived/split-pr/reference/path-layers.md

@@ -1,16 +0,0 @@
-# Path layers — context only
-
-Path-layer labels (database, contracts, backend, frontend, tests, config) are
-**judgment aids**, not hard gates. Vertical slice assignment overrides layer
-buckets when tests must travel with the modules they cover.
-
-| Layer hint | Typical paths |
-|---|---|
-| database | `**/migrations/**`, `**/schema.prisma` |
-| contracts | `**/api/**/types*`, OpenAPI specs |
-| backend | `**/services/**`, `**/handlers/**` |
-| frontend | `**/components/**`, `**/*.tsx` |
-| tests | `**/test_*.py`, `**/*_test.py`, `**/*.test.*` |
-| config | lockfiles, `package.json`, CI workflows |
-
-File count and layer count inform review; they never alone block a plan.

package/.agents/skills-archived/split-pr/reference/proposal-format.md

@@ -1,15 +0,0 @@
-# Split-plan proposal format
-
-Machine-readable plan documents use `schema_version` `1` with:
-
-| Field | Meaning |
-|---|---|
-| `source_commit` | Exact SHA the changed-file list was taken from |
-| `all_changed_paths` | Full path set for that commit |
-| `all_slices` | Ordered slices after layer sort |
-
-Each slice carries `id`, `title` (exactly one conventional prefix), `layer`
-(one of `config` / `backend` / `frontend` / `tests` / `docs` / `other`), and
-`all_paths`. Every path in `all_changed_paths` is assigned to exactly one
-slice. Titles are normalized with `split_pr_title.normalize_split_title`.
-Layer tokens follow `ALL_LAYER_ORDER` in `packages/claude-dev-env/.agents/skills-archived/split-pr/scripts/config/plan_constants.py`.

package/.agents/skills-archived/split-pr/reference/split-further-loop.md

@@ -1,10 +0,0 @@
-# Split-further loop
-
-After the first vertical plan lands as draft slices, re-check each leaf PR:
-
-1. Run the hand-written line analyzer (`scripts/analyze_pr.py`).
-2. If hand-written lines ≥ 200, record a split-analysis artifact.
-3. If hand-written lines ≥ 600 and no atomic exception, propose a further
-   vertical split (tests still co-located with behavior).
-4. Stop when every leaf fits review or carries a Fable-approved atomic
-   exception.

package/.agents/skills-archived/split-pr/reference/splitting-principles.md

@@ -1,26 +0,0 @@
-# Splitting principles — vertical slices
-
-A split plan groups changed paths into **semantic vertical slices**, not layer
-silos. Each slice tells one reviewable story and keeps related tests beside the
-behavior they cover.
-
-## Invariants
-
-1. **Test co-location.** A behavior change and its related tests share one
-   slice. Tests do not land in a later dedicated-test slice by default.
-2. **One story per slice.** Each slice has a single review focus (one vertical
-   capability or one coherent subsystem story).
-3. **Unique path ownership.** Every changed path appears in exactly one slice.
-4. **Green intermediate.** Each stacked intermediate must collect and run the
-   tests that belong to that slice and its bases.
-5. **Preparatory refactors first.** Substantial refactors that do not change
-   product behavior occupy earlier preparatory slices, not mixed with behavior.
-6. **Dependency bases encode merge order.** Slice N+1 bases on slice N when it
-   depends on N's definitions.
-
-## Fable gates
-
-Standing Fable approval is required for:
-
-- a semantic re-bucket that moves paths across slices after the first plan
-- an oversized atomic exception that keeps an unsplittable surface as one PR

package/.agents/skills-archived/split-pr/scripts/analyze_pr.py

@@ -1,279 +0,0 @@
-#!/usr/bin/env python3
-"""Analyze PR churn with the hand-written line metric and 200/600 gates.
-
-::
-
-    python analyze_pr.py --files-json files.json --pretty
-    {"hand_written_lines": 200, "requires_split_analysis": true, ...}
-
-Uses paginated ``gh api .../pulls/N/files`` unless ``--files-json`` is offline.
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import subprocess
-import sys
-from pathlib import Path
-
-from categorize_files import annotate_files, sum_churn_by_class
-from config.split_pr_constants import (
-    CHURN_CLASS_HAND_WRITTEN,
-    DEFAULT_SPLIT_HAND_WRITTEN_LINE_THRESHOLD,
-    EXIT_CODE_FAILURE,
-    EXIT_CODE_SUCCESS,
-    FILE_KEY_ADDITIONS,
-    FILE_KEY_CHANGED_LINES,
-    FILE_KEY_CHURN_CLASS,
-    FILE_KEY_DELETIONS,
-    FILE_KEY_PATH,
-    GH_API_SUBCOMMAND,
-    GH_COMMAND,
-    GH_FILE_ADDITIONS,
-    GH_FILE_DELETIONS,
-    GH_FILE_FILENAME,
-    GH_FILE_PATH,
-    GH_JSON_FLAG,
-    GH_NAME_WITH_OWNER_FIELD,
-    GH_PAGINATE_FLAG,
-    GH_PULLS_FILES_PATH_TEMPLATE,
-    GH_REPO_SUBCOMMAND,
-    GH_SLURP_FLAG,
-    GH_VIEW,
-    JSON_INDENT_SPACES,
-    PAYLOAD_KEY_ALL_FILES,
-    PAYLOAD_KEY_ATOMIC_EXCEPTION,
-    PAYLOAD_KEY_DEFAULT_SPLIT,
-    PAYLOAD_KEY_ERROR,
-    PAYLOAD_KEY_EXCLUDED_CHURN_LINES,
-    PAYLOAD_KEY_FABLE_VERDICT,
-    PAYLOAD_KEY_FILE_COUNT,
-    PAYLOAD_KEY_HAND_WRITTEN_LINES,
-    PAYLOAD_KEY_REASON,
-    PAYLOAD_KEY_REQUIRES_SPLIT_ANALYSIS,
-    SPLIT_ANALYSIS_HAND_WRITTEN_LINE_THRESHOLD,
-    UTF8_ENCODING,
-)
-
-JsonObject = dict[str, object]
-
-
-def build_analysis_from_files(
-    all_file_records: list[JsonObject],
-    *,
-    atomic_exception_reason: str | None = None,
-    fable_verdict: str | None = None,
-) -> JsonObject:
-    """Build the hand-written line analysis document.
-
-    Args:
-        all_file_records: Raw path/additions/deletions maps.
-        atomic_exception_reason: When set at 600+, records an atomic exception.
-        fable_verdict: Standing Fable verdict token required with the exception.
-
-    Returns:
-        Analysis payload with thresholds and optional atomic_exception.
-
-    Raises:
-        ValueError: When an atomic exception is set without a Fable verdict.
-    """
-    all_annotated = annotate_files(all_file_records)
-    hand_written_lines = sum_churn_by_class(
-        all_annotated, churn_class=CHURN_CLASS_HAND_WRITTEN
-    )
-    excluded_churn_lines = 0
-    for each_record in all_annotated:
-        if each_record.get(FILE_KEY_CHURN_CLASS) != CHURN_CLASS_HAND_WRITTEN:
-            excluded_churn_lines += int(
-                each_record.get(FILE_KEY_CHANGED_LINES, 0) or 0
-            )
-    file_count = len(all_annotated)
-    requires_split_analysis = (
-        hand_written_lines >= SPLIT_ANALYSIS_HAND_WRITTEN_LINE_THRESHOLD
-    )
-    default_split = hand_written_lines >= DEFAULT_SPLIT_HAND_WRITTEN_LINE_THRESHOLD
-    analysis: JsonObject = {
-        PAYLOAD_KEY_HAND_WRITTEN_LINES: hand_written_lines,
-        PAYLOAD_KEY_EXCLUDED_CHURN_LINES: excluded_churn_lines,
-        PAYLOAD_KEY_FILE_COUNT: file_count,
-        PAYLOAD_KEY_REQUIRES_SPLIT_ANALYSIS: requires_split_analysis,
-        PAYLOAD_KEY_DEFAULT_SPLIT: default_split,
-        PAYLOAD_KEY_ALL_FILES: all_annotated,
-        PAYLOAD_KEY_ATOMIC_EXCEPTION: None,
-    }
-    if default_split and atomic_exception_reason:
-        if not fable_verdict:
-            raise ValueError(
-                "atomic exception at 600+ hand-written lines requires a "
-                "standing Fable verdict"
-            )
-        analysis[PAYLOAD_KEY_ATOMIC_EXCEPTION] = {
-            PAYLOAD_KEY_REASON: atomic_exception_reason,
-            PAYLOAD_KEY_FABLE_VERDICT: fable_verdict,
-        }
-        analysis[PAYLOAD_KEY_DEFAULT_SPLIT] = False
-    return analysis
-
-
-def _file_records_from_gh(raw_files: object) -> list[JsonObject]:
-    if not isinstance(raw_files, list):
-        return []
-    all_file_records: list[JsonObject] = []
-    for each_file in raw_files:
-        if not isinstance(each_file, dict):
-            continue
-        path = each_file.get(GH_FILE_PATH) or each_file.get(GH_FILE_FILENAME)
-        if not path:
-            continue
-        all_file_records.append(
-            {
-                FILE_KEY_PATH: str(path),
-                FILE_KEY_ADDITIONS: int(each_file.get(GH_FILE_ADDITIONS, 0) or 0),
-                FILE_KEY_DELETIONS: int(each_file.get(GH_FILE_DELETIONS, 0) or 0),
-            }
-        )
-    return all_file_records
-
-
-def _flatten_paginated_file_pages(payload: object) -> list[object]:
-    if not isinstance(payload, list):
-        return []
-    all_files: list[object] = []
-    for each_page in payload:
-        if isinstance(each_page, list):
-            all_files.extend(each_page)
-        elif isinstance(each_page, dict):
-            all_files.append(each_page)
-    return all_files
-
-
-def _load_files_json(files_json_path: Path) -> list[JsonObject]:
-    payload = json.loads(files_json_path.read_text(encoding=UTF8_ENCODING))
-    if not isinstance(payload, list):
-        raise ValueError("files-json must be a JSON array")
-    return _file_records_from_gh(payload)
-
-
-def _resolve_repo_name(repo: str | None) -> str:
-    if repo:
-        return repo
-    completed = subprocess.run(
-        [
-            GH_COMMAND,
-            GH_REPO_SUBCOMMAND,
-            GH_VIEW,
-            GH_JSON_FLAG,
-            GH_NAME_WITH_OWNER_FIELD,
-        ],
-        capture_output=True,
-        text=True,
-        check=False,
-        encoding=UTF8_ENCODING,
-    )
-    if completed.returncode != EXIT_CODE_SUCCESS:
-        raise RuntimeError(
-            completed.stderr.strip()
-            or "gh repo view failed; pass --repo owner/name"
-        )
-    payload = json.loads(completed.stdout)
-    name_with_owner = payload.get(GH_NAME_WITH_OWNER_FIELD)
-    if not name_with_owner:
-        raise RuntimeError("gh repo view returned no nameWithOwner; pass --repo")
-    return str(name_with_owner)
-
-
-def _fetch_pr_files(pr_number: int, repo: str | None) -> list[JsonObject]:
-    resolved_repo = _resolve_repo_name(repo)
-    api_path = GH_PULLS_FILES_PATH_TEMPLATE.format(
-        repo=resolved_repo,
-        pr_number=pr_number,
-    )
-    all_command = [
-        GH_COMMAND,
-        GH_API_SUBCOMMAND,
-        api_path,
-        GH_PAGINATE_FLAG,
-        GH_SLURP_FLAG,
-    ]
-    completed = subprocess.run(
-        all_command,
-        capture_output=True,
-        text=True,
-        check=False,
-        encoding=UTF8_ENCODING,
-    )
-    if completed.returncode != EXIT_CODE_SUCCESS:
-        raise RuntimeError(completed.stderr.strip() or "gh api pulls files failed")
-    payload = json.loads(completed.stdout)
-    return _file_records_from_gh(_flatten_paginated_file_pages(payload))
-
-
-def _analysis_for_cli(
-    all_file_records: list[JsonObject],
-    exception_reason: str | None,
-    standing_verdict: str | None,
-) -> JsonObject:
-    """Map CLI flag values onto the analysis builder kwargs."""
-    return build_analysis_from_files(
-        all_file_records,
-        atomic_exception_reason=exception_reason,
-        fable_verdict=standing_verdict,
-    )
-
-
-def main() -> int:
-    """CLI entry: emit analysis JSON to stdout.
-
-    Returns:
-        Process exit code.
-
-    Raises:
-        Does not raise; converts analysis failures into a JSON error payload.
-    """
-    parser = argparse.ArgumentParser(description="Hand-written line PR analyzer")
-    parser.add_argument("--pr", type=int, default=0, help="PR number for gh fetch")
-    parser.add_argument("--repo", default=None, help="owner/name for gh")
-    parser.add_argument(
-        "--files-json",
-        type=Path,
-        default=None,
-        help="Offline files payload (tests); skips gh",
-    )
-    parser.add_argument(
-        "--atomic-exception-reason",
-        default=None,
-        help="Unsplittable reason when keeping one PR at 600+",
-    )
-    parser.add_argument(
-        "--fable-verdict",
-        default=None,
-        help="Standing Fable verdict token for the atomic exception",
-    )
-    parser.add_argument("--pretty", action="store_true", help="Indent JSON output")
-    parsed = parser.parse_args()
-    try:
-        if parsed.files_json is not None:
-            all_file_records = _load_files_json(parsed.files_json)
-        elif parsed.pr > 0:
-            all_file_records = _fetch_pr_files(parsed.pr, parsed.repo)
-        else:
-            raise ValueError("provide --pr or --files-json")
-        analysis = _analysis_for_cli(
-            all_file_records,
-            parsed.atomic_exception_reason,
-            parsed.fable_verdict,
-        )
-    except (OSError, ValueError, RuntimeError, json.JSONDecodeError) as error:
-        print(
-            json.dumps({PAYLOAD_KEY_ERROR: str(error)}),
-            file=sys.stdout,
-        )
-        return EXIT_CODE_FAILURE
-    indent = JSON_INDENT_SPACES if parsed.pretty else None
-    print(json.dumps(analysis, indent=indent))
-    return EXIT_CODE_SUCCESS
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())