agent-code-guard 0.3.0__tar.gz → 0.3.1__tar.gz

{agent_code_guard-0.3.0/src/agent_code_guard.egg-info → agent_code_guard-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-code-guard
-Version: 0.3.0
+Version: 0.3.1
 Summary: Deterministic cross-language guardrails for agent-assisted development
 License-Expression: MIT
 Project-URL: Source, https://github.com/stef-k/agent-code-guard

{agent_code_guard-0.3.0 → agent_code_guard-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-code-guard"
-version = "0.3.0"
+version = "0.3.1"
 description = "Deterministic cross-language guardrails for agent-assisted development"
 readme = "README.md"
 requires-python = ">=3.10"

{agent_code_guard-0.3.0 → agent_code_guard-0.3.1}/src/agent_code_guard/analysis/adapters.py

@@ -116,11 +116,11 @@ def _range_end_node(node, language: str):
 
 def _callable_range(node, region: ExecutableRegion) -> SourceRange:
     """Snapshot provider points once before mapping them to original source."""
-    start_row, start_column = callable_source_start(node, region.language).start_point
-    end_row, end_column = _range_end_node(node, region.language).end_point
+    start = callable_source_start(node, region.language)
+    end = _range_end_node(node, region.language)
     return SourceRange(
-        region.original_point(start_row, start_column),
-        region.original_point(end_row, end_column),
+        region.original_point_at_byte(start.start_byte),
+        region.original_point_at_byte(end.end_byte),
     )
 
 

{agent_code_guard-0.3.0 → agent_code_guard-0.3.1}/src/agent_code_guard/analysis/callable_identity.py

@@ -272,8 +272,7 @@ def _javascript_lexical_name(node, source: bytes) -> str | None:
 
 
 def _callback_name(node, region: ExecutableRegion) -> str:
-    row, column = node.start_point
-    point = region.original_point(row, column)
+    point = region.original_point_at_byte(node.start_byte)
     return f"<callback@{point.line}:{point.byte_column}>"
 
 

{agent_code_guard-0.3.0 → agent_code_guard-0.3.1}/src/agent_code_guard/analysis/facts.py

@@ -2,8 +2,10 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
+from types import MappingProxyType
+from typing import Mapping
 
 
 @dataclass(frozen=True, order=True)
@@ -82,11 +84,20 @@ class FileFacts:
     controls: tuple[ControlFlowFact, ...]
     decisions: tuple[DecisionFact, ...]
     region_count: int
+    reporting_path: str | None = None
 
 
 @dataclass(frozen=True)
 class AnalysisFacts:
     files: tuple[FileFacts, ...]
+    _reporting_paths: Mapping[Path, str] = field(init=False, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "_reporting_paths", MappingProxyType({
+            file.path: file.reporting_path
+            for file in self.files
+            if file.reporting_path is not None
+        }))
 
     @property
     def callables(self) -> tuple[CallableFact, ...]:
@@ -99,3 +110,12 @@ class AnalysisFacts:
     @property
     def decisions(self) -> tuple[DecisionFact, ...]:
         return tuple(fact for file in self.files for fact in file.decisions)
+
+    def reporting_path_for(self, path: Path, root: Path | None = None) -> str:
+        stored = self._reporting_paths.get(path)
+        if stored is not None:
+            return stored
+        try:
+            return path.relative_to(root).as_posix() if root is not None else path.as_posix()
+        except ValueError:
+            return path.as_posix()

{agent_code_guard-0.3.0 → agent_code_guard-0.3.1}/src/agent_code_guard/analysis/pipeline.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 from dataclasses import dataclass
 from pathlib import Path
 
+from ..invocation import SelectedFile
+
 from .adapters import extract_facts
 from .csharp_compat import corrected_csharp_root
 from .errors import ProviderUnavailableError, SyntaxAnalysisError
@@ -13,16 +15,20 @@ from .provider import ParserProvider, TreeSitterProvider
 from .regions import executable_regions, is_applicable
 
 
-def analyze_files(files: tuple[Path, ...] | list[Path], provider: ParserProvider | None = None) -> AnalysisFacts:
+def analyze_files(files: tuple[SelectedFile, ...] | list[SelectedFile], provider: ParserProvider | None = None) -> AnalysisFacts:
     """Analyze only applicable entries from the already-resolved caller scope."""
     active_provider = provider or TreeSitterProvider()
-    results = [_analyze_file(Path(path), active_provider) for path in files if is_applicable(Path(path))]
+    results = [
+        _analyze_file(selected.physical_path, active_provider, selected.reporting_path)
+        for selected in files if is_applicable(selected.physical_path)
+    ]
     return AnalysisFacts(tuple(results))
 
 
 @dataclass(frozen=True)
 class UnavailableAnalysis:
     path: Path
+    reporting_path: str
     language: str
     kind: str
     message: str
@@ -35,27 +41,27 @@ class BatchAnalysis:
 
 
 def analyze_files_for_runner(
-    files: tuple[Path, ...] | list[Path], provider: ParserProvider | None = None,
+    files: tuple[SelectedFile, ...], provider: ParserProvider | None = None,
 ) -> BatchAnalysis:
     """Analyze selected files independently while retaining only known unavailable evidence."""
     active_provider = provider or TreeSitterProvider()
     results: list[FileFacts] = []
     unavailable: list[UnavailableAnalysis] = []
-    for value in files:
-        path = Path(value)
+    for selected in files:
+        path = selected.physical_path
         if not is_applicable(path):
             continue
         try:
-            results.append(_analyze_file(path, active_provider))
+            results.append(_analyze_file(path, active_provider, selected.reporting_path))
         except (SyntaxAnalysisError, ProviderUnavailableError) as exc:
             if exc.language is None:
                 raise
             kind = "syntax" if isinstance(exc, SyntaxAnalysisError) else "provider"
-            unavailable.append(UnavailableAnalysis(path, exc.language, kind, str(exc)))
+            unavailable.append(UnavailableAnalysis(path, selected.reporting_path, exc.language, kind, str(exc)))
     return BatchAnalysis(AnalysisFacts(tuple(results)), tuple(unavailable))
 
 
-def _analyze_file(path: Path, provider: ParserProvider) -> FileFacts:
+def _analyze_file(path: Path, provider: ParserProvider, reporting_path: str | None = None) -> FileFacts:
     callables = []
     controls = []
     decisions = []
@@ -83,4 +89,4 @@ def _analyze_file(path: Path, provider: ParserProvider) -> FileFacts:
         callables.extend(region_callables)
         controls.extend(region_controls)
         decisions.extend(region_decisions)
-    return FileFacts(path, tuple(callables), tuple(controls), tuple(decisions), len(regions))
+    return FileFacts(path, tuple(callables), tuple(controls), tuple(decisions), len(regions), reporting_path)

{agent_code_guard-0.3.0 → agent_code_guard-0.3.1}/src/agent_code_guard/analysis/regions.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from bisect import bisect_right
 from pathlib import Path
 
 from .errors import SyntaxAnalysisError
@@ -29,21 +30,31 @@ class ExecutableRegion:
     source: bytes
     original_source: bytes
     original_byte_offset: int = 0
+    original_line_starts: tuple[int, ...] | None = None
+    local_line_starts: tuple[int, ...] | None = None
+
+    def __post_init__(self) -> None:
+        if self.original_line_starts is None:
+            object.__setattr__(self, "original_line_starts", _line_starts(self.original_source))
+        if self.local_line_starts is None:
+            object.__setattr__(self, "local_line_starts", _line_starts(self.source))
 
     def original_point(self, local_row: int, local_byte_column: int) -> SourcePoint:
-        absolute = self.original_byte_offset + _byte_at_point(self.source, local_row, local_byte_column)
-        prefix = self.original_source[:absolute]
-        line = prefix.count(b"\n") + 1
-        newline = prefix.rfind(b"\n")
-        byte_column = absolute + 1 if newline < 0 else absolute - newline
+        local_offset = self.local_line_starts[local_row] + local_byte_column
+        return self.original_point_at_byte(local_offset)
+
+    def original_point_at_byte(self, local_byte_offset: int) -> SourcePoint:
+        """Map a parser byte offset without reconstructing its local row prefix."""
+        absolute = self.original_byte_offset + local_byte_offset
+        row = bisect_right(self.original_line_starts, absolute) - 1
+        line = row + 1
+        byte_column = absolute - self.original_line_starts[row] + 1
         return SourcePoint(line, byte_column, absolute)
 
     def original_range(self, node) -> SourceRange:
-        start_row, start_column = node.start_point
-        end_row, end_column = node.end_point
         return SourceRange(
-            self.original_point(start_row, start_column),
-            self.original_point(end_row, end_column),
+            self.original_point_at_byte(node.start_byte),
+            self.original_point_at_byte(node.end_byte),
         )
 
 
@@ -69,6 +80,7 @@ def _vue_regions(path: Path, source: bytes, provider: ParserProvider) -> tuple[E
             f"unable to parse {path}: Vue container syntax tree contains errors", language="vue",
         )
     regions: list[ExecutableRegion] = []
+    original_line_starts = _line_starts(source)
     for element in root.named_children:
         if element.type != "script_element":
             continue
@@ -83,15 +95,13 @@ def _vue_regions(path: Path, source: bytes, provider: ParserProvider) -> tuple[E
         if raw_text is not None:
             regions.append(ExecutableRegion(
                 path, language, source[raw_text.start_byte:raw_text.end_byte], source, raw_text.start_byte,
+                original_line_starts,
             ))
     return tuple(regions)
 
 
-def _byte_at_point(source: bytes, row: int, column: int) -> int:
-    position = 0
-    for _ in range(row):
-        position = source.index(b"\n", position) + 1
-    return position + column
+def _line_starts(source: bytes) -> tuple[int, ...]:
+    return (0, *(index + 1 for index, value in enumerate(source) if value == 10))
 
 
 def _attributes(start_tag, source: bytes) -> dict[str, str | None]:

{agent_code_guard-0.3.0 → agent_code_guard-0.3.1}/src/agent_code_guard/code_guard.py

@@ -12,12 +12,12 @@ import sys
 from pathlib import Path
 
 from .config_validation import validate_configuration
-from .file_selection import resolve_scope
+from .file_selection import ResolvedScope, resolve_invocation, resolve_scope
 from .guards import callable_size, complexity, loc, markdown_document_size, markdown_section_size, nesting
 from .human_output import format_completed_analysis
 from . import loc_baseline
 from .result_model import GuardResult, aggregate_state, required_policies
-from .reporting import reporting_path
+from .invocation import AnalysisContext, SelectedFile, load_configuration
 from .skill_distribution import export_skill, skill_path as installed_skill_path
 
 DISTRIBUTION_NAME = "agent-code-guard"
@@ -329,63 +329,78 @@ def run_guards(scope, args: argparse.Namespace) -> list[GuardResult]:
 
 
 def run_analysis(
-    scope, args: argparse.Namespace, baseline_override: dict[str, int] | None = None,
+    scope: AnalysisContext | ResolvedScope, args: argparse.Namespace, baseline_override: dict[str, int] | None = None,
     baseline_loaded: bool = False, linked_targets: set[Path] | None = None,
 ) -> CompletedAnalysis:
     """Load guard configuration, then construct shared syntax facts at most once."""
-    loc_config = loc.load_config(args)
-    baseline = baseline_override if baseline_loaded else loc_baseline.load_if_present(scope.root)
+    context = scope if isinstance(scope, AnalysisContext) else _legacy_context(scope, args)
+    loc_config = loc.load_config(args, context.configuration)
+    baseline = baseline_override if baseline_loaded else loc_baseline.load_if_present(context.root)
     if baseline is not None:
-        loc_baseline.validate_paths(scope.root, baseline)
+        loc_baseline.validate_paths(context.root, baseline)
         loc_baseline.validate_overlap(baseline, loc_config)
-        for path in scope.files:
-            if not path.is_file() or not path.resolve().is_relative_to(scope.root.resolve()):
-                raise ValueError(f"baseline analysis scope is outside analysis root: {path}")
+        error = "baseline analysis scope is outside analysis root"
+        try:
+            current_root = context.root.resolve(strict=True)
+        except OSError as exc:
+            raise ValueError(f"{error}: {context.root}") from exc
+        for selected in context.selected_files:
+            try:
+                current_path = selected.physical_path.resolve(strict=True)
+                valid = (
+                    not selected.physical_path.is_symlink()
+                    and current_path.is_file()
+                    and current_path.is_relative_to(current_root)
+                )
+            except OSError:
+                valid = False
+            if not valid:
+                raise ValueError(f"{error}: {selected.physical_path}")
         baseline = dict(baseline)
         for target in linked_targets or set():
-            baseline.pop(target.relative_to(scope.root).as_posix(), None)
-    callable_size_config = callable_size.load_config(args)
-    nesting_config = nesting.load_config(args)
-    complexity_config = complexity.load_config(args)
-    markdown_document_config = markdown_document_size.load_config(args)
-    markdown_section_config = markdown_section_size.load_config(args)
-    results = [loc.run(scope.root, loc_config, scope.files, baseline)]
+            baseline.pop(target.relative_to(context.root).as_posix(), None)
+    callable_size_config = callable_size.load_config(args, context.configuration)
+    nesting_config = nesting.load_config(args, context.configuration)
+    complexity_config = complexity.load_config(args, context.configuration)
+    markdown_document_config = markdown_document_size.load_config(args, context.configuration)
+    markdown_section_config = markdown_section_size.load_config(args, context.configuration)
+    results = [loc.run(context.root, loc_config, context.selected_files, baseline)]
     analyzed_files = {
-        path for path in scope.files
-        if loc_config.enabled and loc.should_include(path, loc_config, scope.root)
+        selected.reporting_path for selected in context.selected_files
+        if loc_config.enabled and loc.should_include(selected, loc_config)
     }
     needs_analysis = callable_size_config.enabled or nesting_config.enabled or complexity_config.enabled
     if needs_analysis:
         analysis = import_module("agent_code_guard.analysis.pipeline")
-        analyzed_files.update(path for path in scope.files if analysis.is_applicable(path))
-        batch = analysis.analyze_files_for_runner(scope.files)
+        analyzed_files.update(selected.reporting_path for selected in context.selected_files if analysis.is_applicable(selected.physical_path))
+        batch = analysis.analyze_files_for_runner(context.selected_files)
         facts = batch.facts
         if callable_size_config.enabled:
-            results.append(callable_size.run(scope.root, callable_size_config, facts))
+            results.append(callable_size.run(context.root, callable_size_config, facts))
         if nesting_config.enabled:
-            results.append(nesting.run(scope.root, nesting_config, facts))
+            results.append(nesting.run(context.root, nesting_config, facts))
         if complexity_config.enabled:
-            results.append(complexity.run(scope.root, complexity_config, facts))
+            results.append(complexity.run(context.root, complexity_config, facts))
     needs_markdown = markdown_document_config.enabled or markdown_section_config.enabled
-    markdown_files = tuple(path for path in scope.files if path.suffix.lower() == ".md") if needs_markdown else ()
-    analyzed_files.update(markdown_files)
+    markdown_files = tuple(selected for selected in context.selected_files if selected.physical_path.suffix.lower() == ".md") if needs_markdown else ()
+    analyzed_files.update(selected.reporting_path for selected in markdown_files)
     if markdown_files:
         markdown = import_module("agent_code_guard.markdown")
         markdown_facts = markdown.analyze_files(markdown_files)
         if markdown_document_config.enabled:
-            results.append(markdown_document_size.run(scope.root, markdown_document_config, markdown_facts))
+            results.append(markdown_document_size.run(context.root, markdown_document_config, markdown_facts))
         if markdown_section_config.enabled:
-            results.append(markdown_section_size.run(scope.root, markdown_section_config, markdown_facts))
+            results.append(markdown_section_size.run(context.root, markdown_section_config, markdown_facts))
     else:
         if markdown_document_config.enabled:
-            results.append(markdown_document_size.run(scope.root, markdown_document_config, _empty_markdown_facts()))
+            results.append(markdown_document_size.run(context.root, markdown_document_config, _empty_markdown_facts()))
         if markdown_section_config.enabled:
-            results.append(markdown_section_size.run(scope.root, markdown_section_config, _empty_markdown_facts()))
-    selected = len(scope.files)
+            results.append(markdown_section_size.run(context.root, markdown_section_config, _empty_markdown_facts()))
+    selected = len(context.selected_files)
     analyzed = len(analyzed_files)
     unavailable = tuple(
         UnavailableEntry(
-            reporting_path(item.path, scope.root), item.language, item.kind, item.message,
+            item.reporting_path, item.language, item.kind, item.message,
         )
         for item in (batch.unavailable if needs_analysis else ())
     )
@@ -399,7 +414,7 @@ def run_analysis(
     return CompletedAnalysis(
         results,
         ScopeSummary(
-            selected, analyzed, selected - analyzed, len(scope.excluded_files),
+            selected, analyzed, selected - analyzed, len(context.excluded_files),
             len({entry.path for entry in unavailable}) if unavailable else None,
         ),
         unavailable,
@@ -407,6 +422,21 @@ def run_analysis(
     )
 
 
+def _legacy_context(scope: ResolvedScope, args: argparse.Namespace) -> AnalysisContext:
+    """Focused-test adapter; the production runner constructs identities during selection."""
+    document = validate_configuration(args.config, Path.cwd())
+    def selected(path: Path) -> SelectedFile:
+        try:
+            report = path.relative_to(scope.root).as_posix()
+        except ValueError:
+            report = path.as_posix()
+        return SelectedFile(report, path)
+    return AnalysisContext(
+        scope.root, document, tuple(selected(path) for path in scope.files),
+        tuple(selected(path) for path in scope.excluded_files),
+    )
+
+
 def _empty_markdown_facts():
     """Avoid importing the scanner family for scopes with no applicable files."""
     from types import SimpleNamespace
@@ -455,13 +485,16 @@ def main() -> int:
         management_result = _management_mode(args)
         if management_result is not None:
             return management_result
-        validate_configuration(args.config, Path.cwd())
-        scope = resolve_scope(args, Path.cwd())
+        invocation = Path.cwd()
+        configuration = load_configuration(args.config, invocation)
+        validate_configuration(args.config, invocation, configuration)
+        scope = resolve_invocation(args, invocation, configuration)
         linked_targets: set[Path] = set()
         baseline_loaded = hasattr(scope, "root")
         if baseline_loaded and loc_baseline.baseline_path(scope.root).exists():
             linked_targets = loc_baseline.validate_explicit_scope(
-                args.paths, Path.cwd(), scope.root, scope.files,
+                args.paths, invocation, scope.root,
+                tuple(selected.physical_path for selected in scope.selected_files),
             )
         baseline = loc_baseline.load_if_present(scope.root) if baseline_loaded else None
         data = payload(

{agent_code_guard-0.3.0 → agent_code_guard-0.3.1}/src/agent_code_guard/config_validation.py

@@ -2,10 +2,12 @@
 
 from __future__ import annotations
 
-import json
 from pathlib import Path
+from collections.abc import Mapping, Sequence
 from typing import Any
 
+from .invocation import load_configuration
+
 ROOT_KEYS = {"version", "scope", "guards"}
 SCOPE_KEYS = {"exclude"}
 GUARD_KEYS = {
@@ -40,28 +42,23 @@ LOC_ALLOWED_LARGE_FILE_KEYS = {"path", "reason"}
 LOC_OVERRIDE_KEYS = {"match", "warnAt", "failAt"}
 
 
-def validate_configuration(config: str | None, start: Path) -> None:
-    """Load the configured document once and validate its known property names."""
-    path = Path(config) if config else start / ".agent-tools" / "code-guard.config.json"
-    if config and not path.exists():
-        raise FileNotFoundError(f"config file not found: {config}")
-    if not path.exists():
-        return
-    document = json.loads(path.read_text(encoding="utf-8"))
-    if not isinstance(document, dict):
-        raise ValueError("configuration must be an object")
+def validate_configuration(
+    config: str | None, start: Path, document: Mapping[str, Any] | None = None,
+) -> Mapping[str, Any]:
+    """Validate known property names in an already-loaded document."""
+    document = load_configuration(config, start) if document is None else document
     _reject_unknown(document, ROOT_KEYS, "")
     _validate_object_keys(document.get("scope"), SCOPE_KEYS, "scope")
 
     guards = document.get("guards")
-    if not isinstance(guards, dict):
-        return
+    if not isinstance(guards, Mapping):
+        return document
     _reject_unknown(guards, GUARD_KEYS, "guards")
     for guard_name in REVIEW_GUARD_NAMES:
         _validate_object_keys(guards.get(guard_name), REVIEW_GUARD_KEYS, f"guards.{guard_name}")
     loc = guards.get("loc")
-    if not isinstance(loc, dict):
-        return
+    if not isinstance(loc, Mapping):
+        return document
     _reject_unknown(loc, LOC_KEYS, "guards.loc")
     _validate_items(
         loc.get("allowedLargeFiles"),
@@ -69,22 +66,23 @@ def validate_configuration(config: str | None, start: Path) -> None:
         "guards.loc.allowedLargeFiles",
     )
     _validate_items(loc.get("overrides"), LOC_OVERRIDE_KEYS, "guards.loc.overrides")
+    return document
 
 
 def _validate_object_keys(value: Any, allowed: set[str], path: str) -> None:
-    if isinstance(value, dict):
+    if isinstance(value, Mapping):
         _reject_unknown(value, allowed, path)
 
 
 def _validate_items(value: Any, allowed: set[str], path: str) -> None:
-    if not isinstance(value, list):
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes)):
         return
     for index, item in enumerate(value):
-        if isinstance(item, dict):
+        if isinstance(item, Mapping):
             _reject_unknown(item, allowed, f"{path}[{index}]")
 
 
-def _reject_unknown(value: dict[str, Any], allowed: set[str], path: str) -> None:
+def _reject_unknown(value: Mapping[str, Any], allowed: set[str], path: str) -> None:
     unknown = sorted(key for key in value if key not in allowed)
     if unknown:
         property_path = f"{path}.{unknown[0]}" if path else unknown[0]

{agent_code_guard-0.3.0 → agent_code_guard-0.3.1}/src/agent_code_guard/file_selection.py

@@ -2,13 +2,14 @@
 
 from __future__ import annotations
 
-import json
 import os
 import subprocess
+from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Protocol
 
+from .invocation import AnalysisContext, JsonObject, SelectedFile
 from .path_matching import matches_path_glob, relative_or_absolute_path
 
 BUILTIN_PRUNED_DIRECTORIES = {".git", "node_modules", "bin", "obj"}
@@ -30,6 +31,19 @@ class ResolvedScope:
     excluded_files: tuple[Path, ...] = ()
 
 
+def resolve_invocation(
+    args: SelectionArgs, start: Path, configuration: JsonObject,
+) -> AnalysisContext:
+    """Resolve every physical/reporting identity once for one invocation."""
+    scope = _resolve_scope(args, start, configuration)
+    return AnalysisContext(
+        scope.root,
+        configuration,
+        tuple(SelectedFile(_reporting_path(path, scope.root), path) for path in scope.files),
+        tuple(SelectedFile(_reporting_path(path, scope.root), path) for path in scope.excluded_files),
+    )
+
+
 def find_repo_root(start: Path) -> Path | None:
     """Return the enclosing Git root, without inventing one when Git is absent."""
     try:
@@ -37,14 +51,19 @@ def find_repo_root(start: Path) -> Path | None:
             ["git", "rev-parse", "--show-toplevel"], cwd=start, check=True,
             text=True, capture_output=True,
         )
-        return Path(result.stdout.strip()).resolve()
+        return _canonicalize(Path(result.stdout.strip()))
     except Exception:
         return None
 
 
 def resolve_scope(args: SelectionArgs, start: Path) -> ResolvedScope:
     """Resolve and normalize the complete file scope shared by all guards."""
-    working_root = start.resolve()
+    from .invocation import load_configuration
+    return _resolve_scope(args, start, load_configuration(getattr(args, "config", None), start))
+
+
+def _resolve_scope(args: SelectionArgs, start: Path, configuration: JsonObject) -> ResolvedScope:
+    working_root = _canonicalize(start)
     git_root = find_repo_root(working_root)
     root = git_root or working_root
     validate_selection_args(args, git_root)
@@ -59,16 +78,24 @@ def resolve_scope(args: SelectionArgs, start: Path) -> ResolvedScope:
     else:
         files = existing_files(expand_paths(paths, git_root))
 
-    normalized = tuple(dict.fromkeys(path.resolve() for path in files))
-    exclusions = load_scope_exclusions(args, working_root)
+    normalized = tuple(dict.fromkeys(_canonicalize(path) for path in files))
+    exclusions = load_scope_exclusions(args, configuration)
+    identities = tuple((path, _reporting_path(path, root)) for path in normalized)
     excluded = tuple(
-        path for path in normalized
-        if any(matches_path_glob(relative_or_absolute_path(path, root), pattern) for pattern in exclusions)
+        path for path, reporting_path in identities
+        if any(matches_path_glob(reporting_path, pattern) for pattern in exclusions)
     )
     excluded_set = set(excluded)
     return ResolvedScope(root, tuple(path for path in normalized if path not in excluded_set), excluded)
 
 
+def _reporting_path(canonical_path: Path, canonical_root: Path) -> str:
+    try:
+        return canonical_path.relative_to(canonical_root).as_posix()
+    except ValueError:
+        return canonical_path.as_posix()
+
+
 def resolve_explicit_paths(values: list[str], working_root: Path) -> list[Path]:
     """Resolve and validate positional paths against the caller's working directory."""
     paths = [Path(value) if Path(value).is_absolute() else working_root / value for value in values]
@@ -83,6 +110,11 @@ def resolve_explicit_paths(values: list[str], working_root: Path) -> list[Path]:
     return paths
 
 
+def _canonicalize(path: Path) -> Path:
+    """Owned filesystem identity seam; never call it from guard loops."""
+    return path.resolve()
+
+
 def bound_git_candidates(candidates: list[Path], bounds: list[Path]) -> list[Path]:
     """Intersect Git-selected files with the union of positional file/directory bounds."""
     normalized_bounds = [(path.resolve(), path.is_dir()) for path in bounds]
@@ -95,19 +127,12 @@ def bound_git_candidates(candidates: list[Path], bounds: list[Path]) -> list[Pat
     ]
 
 
-def load_scope_exclusions(args: SelectionArgs, start: Path) -> list[str]:
-    explicit_config = getattr(args, "config", None)
-    config_path = Path(explicit_config) if explicit_config else start / ".agent-tools" / "code-guard.config.json"
-    if explicit_config and not config_path.exists():
-        raise FileNotFoundError(f"config file not found: {explicit_config}")
-    document = json.loads(config_path.read_text(encoding="utf-8")) if config_path.exists() else {}
-    if not isinstance(document, dict):
-        raise ValueError("configuration must be an object")
+def load_scope_exclusions(args: SelectionArgs, document: JsonObject) -> list[str]:
     scope = document.get("scope", {})
-    if not isinstance(scope, dict):
+    if not isinstance(scope, Mapping):
         raise ValueError("scope must be an object")
     exclude = scope.get("exclude", [])
-    if not isinstance(exclude, list) or any(not isinstance(pattern, str) for pattern in exclude):
+    if not isinstance(exclude, Sequence) or isinstance(exclude, (str, bytes)) or any(not isinstance(pattern, str) for pattern in exclude):
         raise ValueError("scope.exclude must be an array of strings")
     combined = [*exclude, *getattr(args, "scope_exclude", [])]
     if any(not isinstance(pattern, str) or not pattern.strip() for pattern in combined):