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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-code-guard
-Version: 0.2.0
+Version: 0.3.0
 Summary: Deterministic cross-language guardrails for agent-assisted development
 License-Expression: MIT
 Project-URL: Source, https://github.com/stef-k/agent-code-guard
@@ -82,16 +82,28 @@ environment, uv, and developer alternatives.
 
 Copy this prompt to a coding agent:
 
-> Consult the official Agent Code Guard repository and documentation. Install
-> the published distribution in an isolated supported way, preferably with
-> pipx; verify `code-guard --version` and run `code-guard doctor`. Locate the
-> installed version-matched skill with `code-guard --skill-path`, and use or
-> export only that skill through the documented mechanism. Inspect this
-> repository without creating a LOC baseline and use changed-work scope. Ask
-> before exporting into a persistent skill directory, changing persistent
-> agent or platform configuration, or configuring hooks.
-> Never weaken thresholds, exclusions, configuration, or baselines merely to
-> silence findings.
+> Adopt Agent Code Guard for this repository using the official project and
+> documentation at https://github.com/stef-k/agent-code-guard. This prompt
+> authorizes installing the published distribution in an isolated supported
+> way, preferably with `pipx install agent-code-guard`, and persistently
+> activating or exporting its installed, version-matched skill for the current
+> agent environment. Verify `code-guard --version` and run `code-guard doctor`,
+> then locate the skill with `code-guard --skill-path`. Follow the
+> [skill activation guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md):
+> activate that installed path when the platform supports it, or export it with
+> `code-guard --export-skill <target-directory>` to the platform's documented
+> skill directory. Do not guess a target or overwrite an existing export; verify
+> that `.agent-code-guard-version` matches the installed distribution. Follow the
+> [agent workflow](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md)
+> without creating a LOC baseline. After meaningful source or Markdown edits, run
+> `code-guard . --changed-only --json --json-mode compact`; outside Git, pass the
+> exact edited files. Inspect REVIEW and FAIL findings, make only genuine
+> improvements, rerun the check, and report the result. Never weaken thresholds,
+> exclusions, configuration, or baselines merely to silence findings. Code Guard
+> does not install or enable hooks by default. Ask before configuring a post-edit
+> or post-turn hook, or making unrelated persistent agent or platform changes.
+> Finish by reporting the installed version, doctor status, activated skill
+> location, first analysis result, and any REVIEW findings you accepted.
 
 ## Five-minute start
 
@@ -138,12 +150,14 @@ hook-assisted process.
   warranted; normally exit `1`.
 - **Completed FAIL** — blocks normal completion until fixed or an explicitly
   authorized exception applies; exit `2` with a completed report on stdout.
+- **INCOMPLETE** — one or more requested syntax analyses are unavailable;
+  independent completed findings remain authoritative, but the run exits `3`.
 - An argparse usage or invalid-choice error exits `2`, writes usage/error text
   to stderr, and produces no completed report.
-- Other Code Guard tool, configuration, scope, or provider errors exit `3`.
+- Other Code Guard tool, configuration, scope, or unexpected errors exit `3`.
 
 `--ci` makes REVIEW nonblocking at the process level by changing its exit to
-`0`; it does not hide the findings or change FAIL and tool-error exits.
+`0`; it does not hide findings or change FAIL, INCOMPLETE, and tool-error exits.
 
 **Never game a metric.** Do not create artificial helpers, files,
 abstractions, formatting, exclusions, or policy changes merely to lower a
@@ -175,6 +189,12 @@ result, scope, required policies, guards, ordering, and actionable findings.
 Named modes require `--json`. See [Usage](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md) for the schema and
 option contract.
 
+Known per-file syntax or provider failures instead produce `overall:
+"incomplete"`, ordered structured `unavailable` records, and completed guard
+evidence. Syntax guards identify unavailable paths; LOC and Markdown remain
+complete. Full, debug, and compact JSON retain unavailable records unchanged,
+and completed runs retain their existing schema.
+
 ### Common scope commands
 
 ```bash
@@ -200,7 +220,8 @@ Markdown guards apply to `.md` files.
 Generic `.h` files are not syntax-dispatched; `.markdown` is not enabled; Vue
 template and style regions are not executable syntax input; and unsupported
 artifacts are inapplicable. Malformed applicable syntax or a required provider
-failure is a fail-closed tool error. See [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md).
+failure is unavailable evidence, distinct from both an inapplicable file and a
+completed FAIL finding. See [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md).
 
 ### Skill integration
 
@@ -221,6 +242,9 @@ Built-in defaults require no configuration. Configure a project only for a
 concrete policy reason; see the [configuration guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/configuration.md).
 The LOC baseline is an explicit adoption tool for established legacy
 repositories, not an ordinary-use requirement or a way to silence findings.
+Its default `ratchetAt: "fail"` policy freezes files above `failAt`; choose
+`ratchetAt: "review"` only when every established file above `warnAt` must be
+non-increasing while ordinary findings in that range remain REVIEW.
 
 ## Trust, CI, and platform support
 

{agent_code_guard-0.2.0 → agent_code_guard-0.3.0}/README.md

@@ -68,16 +68,28 @@ environment, uv, and developer alternatives.
 
 Copy this prompt to a coding agent:
 
-> Consult the official Agent Code Guard repository and documentation. Install
-> the published distribution in an isolated supported way, preferably with
-> pipx; verify `code-guard --version` and run `code-guard doctor`. Locate the
-> installed version-matched skill with `code-guard --skill-path`, and use or
-> export only that skill through the documented mechanism. Inspect this
-> repository without creating a LOC baseline and use changed-work scope. Ask
-> before exporting into a persistent skill directory, changing persistent
-> agent or platform configuration, or configuring hooks.
-> Never weaken thresholds, exclusions, configuration, or baselines merely to
-> silence findings.
+> Adopt Agent Code Guard for this repository using the official project and
+> documentation at https://github.com/stef-k/agent-code-guard. This prompt
+> authorizes installing the published distribution in an isolated supported
+> way, preferably with `pipx install agent-code-guard`, and persistently
+> activating or exporting its installed, version-matched skill for the current
+> agent environment. Verify `code-guard --version` and run `code-guard doctor`,
+> then locate the skill with `code-guard --skill-path`. Follow the
+> [skill activation guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md):
+> activate that installed path when the platform supports it, or export it with
+> `code-guard --export-skill <target-directory>` to the platform's documented
+> skill directory. Do not guess a target or overwrite an existing export; verify
+> that `.agent-code-guard-version` matches the installed distribution. Follow the
+> [agent workflow](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md)
+> without creating a LOC baseline. After meaningful source or Markdown edits, run
+> `code-guard . --changed-only --json --json-mode compact`; outside Git, pass the
+> exact edited files. Inspect REVIEW and FAIL findings, make only genuine
+> improvements, rerun the check, and report the result. Never weaken thresholds,
+> exclusions, configuration, or baselines merely to silence findings. Code Guard
+> does not install or enable hooks by default. Ask before configuring a post-edit
+> or post-turn hook, or making unrelated persistent agent or platform changes.
+> Finish by reporting the installed version, doctor status, activated skill
+> location, first analysis result, and any REVIEW findings you accepted.
 
 ## Five-minute start
 
@@ -124,12 +136,14 @@ hook-assisted process.
   warranted; normally exit `1`.
 - **Completed FAIL** — blocks normal completion until fixed or an explicitly
   authorized exception applies; exit `2` with a completed report on stdout.
+- **INCOMPLETE** — one or more requested syntax analyses are unavailable;
+  independent completed findings remain authoritative, but the run exits `3`.
 - An argparse usage or invalid-choice error exits `2`, writes usage/error text
   to stderr, and produces no completed report.
-- Other Code Guard tool, configuration, scope, or provider errors exit `3`.
+- Other Code Guard tool, configuration, scope, or unexpected errors exit `3`.
 
 `--ci` makes REVIEW nonblocking at the process level by changing its exit to
-`0`; it does not hide the findings or change FAIL and tool-error exits.
+`0`; it does not hide findings or change FAIL, INCOMPLETE, and tool-error exits.
 
 **Never game a metric.** Do not create artificial helpers, files,
 abstractions, formatting, exclusions, or policy changes merely to lower a
@@ -161,6 +175,12 @@ result, scope, required policies, guards, ordering, and actionable findings.
 Named modes require `--json`. See [Usage](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md) for the schema and
 option contract.
 
+Known per-file syntax or provider failures instead produce `overall:
+"incomplete"`, ordered structured `unavailable` records, and completed guard
+evidence. Syntax guards identify unavailable paths; LOC and Markdown remain
+complete. Full, debug, and compact JSON retain unavailable records unchanged,
+and completed runs retain their existing schema.
+
 ### Common scope commands
 
 ```bash
@@ -186,7 +206,8 @@ Markdown guards apply to `.md` files.
 Generic `.h` files are not syntax-dispatched; `.markdown` is not enabled; Vue
 template and style regions are not executable syntax input; and unsupported
 artifacts are inapplicable. Malformed applicable syntax or a required provider
-failure is a fail-closed tool error. See [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md).
+failure is unavailable evidence, distinct from both an inapplicable file and a
+completed FAIL finding. See [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md).
 
 ### Skill integration
 
@@ -207,6 +228,9 @@ Built-in defaults require no configuration. Configure a project only for a
 concrete policy reason; see the [configuration guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/configuration.md).
 The LOC baseline is an explicit adoption tool for established legacy
 repositories, not an ordinary-use requirement or a way to silence findings.
+Its default `ratchetAt: "fail"` policy freezes files above `failAt`; choose
+`ratchetAt: "review"` only when every established file above `warnAt` must be
+non-increasing while ordinary findings in that range remain REVIEW.
 
 ## Trust, CI, and platform support
 

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

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

{agent_code_guard-0.2.0 → agent_code_guard-0.3.0}/skills/code-guard/SKILL.md

@@ -15,6 +15,7 @@ Code Guard provides deterministic measurements that act as anchors for agent jud
 - `PASS` — no special action is required.
 - `REVIEW` — inspect the finding and either accept it with a meaningful justification or improve the code when doing so improves real clarity, cohesion, or boundaries.
 - `FAIL` — do not declare normal completion until the condition is fixed or an explicitly permitted/user-approved exception applies.
+- `INCOMPLETE` — known per-file syntax or provider evidence is unavailable; retain and report independent completed evidence, but do not declare normal completion.
 
 ## Universal rules
 
@@ -50,10 +51,11 @@ python3 skills/code-guard/scripts/code_guard.py . --changed-only
 ```
 
 `pyproject.toml` canonically owns the production pins. Tree-sitter remains
-dormant during LOC-only execution; failure to load a required provider or
-grammar is a deterministic tool error during normal zero-config syntax analysis.
-Disabling every syntax guard preserves the lazy no-Tree-sitter path. A strictly
-LOC-only result also requires both Markdown guards to be explicitly disabled.
+dormant during LOC-only execution. A known per-file provider, grammar, or syntax
+failure produces blocking `INCOMPLETE` output while retaining independent LOC,
+Markdown, and unaffected syntax evidence. Disabling every syntax guard preserves
+the lazy no-Tree-sitter path. A strictly LOC-only result also requires both
+Markdown guards to be explicitly disabled.
 
 Without Git, pass exactly the files you created or modified. You are
 responsible for supplying the complete edited-file set:
@@ -75,8 +77,9 @@ project exclusions. LOC `--exclude` remains LOC-specific. Explicit files may
 intentionally inspect Git-ignored or built-in-pruned artifacts, unless Code
 Guard `scope.exclude` or `--scope-exclude` removes them.
 
-Inspect every REVIEW and FAIL. When all guards return `PASS`, no detailed
-policy file needs to be loaded.
+Inspect every REVIEW and FAIL. Treat INCOMPLETE as blocking, preserve its
+completed findings, and report its unavailable paths and failure context. When
+all guards return `PASS`, no detailed policy file needs to be loaded.
 
 When a guard returns `REVIEW` or `FAIL`, read only the policy file named by that finding. The runner returns required policy identifiers/files in both human-readable and JSON output.
 
@@ -103,10 +106,10 @@ code-guard . --changed-only --ci --json --json-mode compact
 ```
 
 `--ci` makes REVIEW exit `0`, but REVIEW remains visible and requires
-judgment; FAIL remains `2` and tool errors remain `3`. Outside Git, a hook
-must supply the exact edited files. Do not install hooks, export into persistent
-skill directories, or modify persistent user or repository configuration
-without authorization.
+judgment; FAIL remains `2`, and INCOMPLETE and tool errors remain `3`. Outside
+Git, a hook must supply the exact edited files. Do not install hooks, export
+into persistent skill directories, or modify persistent user or repository
+configuration without authorization.
 
 ## Scope
 

{agent_code_guard-0.2.0 → agent_code_guard-0.3.0}/skills/code-guard/references/loc-policy.md

@@ -27,6 +27,15 @@ Existing `allowedLargeFiles` entries may be honored with their configured reason
 
 Do not infer approval from inconvenience, historical size, a nearby exemption, time pressure, or a request to finish the coding task.
 
+## Source-controlled ratchets
+
+An established repository may use `guards.loc.ratchetAt: "fail"` (the default)
+to freeze only files already above `failAt`, or `"review"` to freeze every
+recorded file above `warnAt` while retaining ordinary REVIEW semantics within
+its allowance. Growth above a recorded allowance is always FAIL. Never switch
+the policy, raise thresholds, add exclusions or exemptions, or increase/remove
+allowances merely to silence growth.
+
 ## Do not game LOC
 
 Project formatting conventions take priority. Never combine independent statements, compress control flow or expressions unusually, minify handwritten code, remove useful comments/structure, or fight the formatter merely to lower physical LOC.

agent_code_guard-0.3.0/src/agent_code_guard/analysis/csharp_compat.py

@@ -0,0 +1,115 @@
+"""Narrow compatibility correction for upstream C# contextual-keyword errors."""
+
+from __future__ import annotations
+
+
+_CONTEXTUAL_KEYWORD = b"async"
+_NEUTRAL_IDENTIFIER = b"azync"
+_EXPRESSION_CONTAINERS = {
+    "argument", "arrow_expression_clause", "expression_statement", "return_statement",
+}
+_NON_EXPRESSION_FIELDS = {"alias", "label", "name", "type"}
+
+
+def corrected_csharp_root(provider, source: bytes, first_tree):
+    """Return one verified corrected root, or ``None`` when correction is unsafe."""
+    problems = tuple(_problem_nodes(first_tree.root_node))
+    if not problems:
+        return None
+
+    token_offsets: set[int] = set()
+    for problem in problems:
+        candidates = _contained_unescaped_tokens(source, problem.start_byte, problem.end_byte)
+        if len(candidates) > 1:
+            candidates = tuple(
+                offset
+                for offset in candidates
+                if not _is_declaration_identifier(first_tree.root_node, offset)
+            )
+        if len(candidates) != 1:
+            return None
+        token_offsets.add(candidates[0])
+
+    corrected = bytearray(source)
+    for offset in token_offsets:
+        corrected[offset:offset + len(_CONTEXTUAL_KEYWORD)] = _NEUTRAL_IDENTIFIER
+    corrected_source = bytes(corrected)
+    if len(corrected_source) != len(source) or _newline_offsets(corrected_source) != _newline_offsets(source):
+        return None
+
+    retry_tree = provider.parse("csharp", corrected_source)
+    if retry_tree.root_node.has_error or any(_problem_nodes(retry_tree.root_node)):
+        return None
+    if not all(_has_authorized_role(retry_tree.root_node, offset) for offset in token_offsets):
+        return None
+    return retry_tree.root_node
+
+
+def _problem_nodes(node):
+    if node.is_error or node.is_missing:
+        yield node
+    for child in node.children:
+        yield from _problem_nodes(child)
+
+
+def _contained_unescaped_tokens(source: bytes, start: int, end: int) -> tuple[int, ...]:
+    offsets: list[int] = []
+    position = source.find(_CONTEXTUAL_KEYWORD, start, end)
+    while position >= 0:
+        token_end = position + len(_CONTEXTUAL_KEYWORD)
+        if token_end <= end and _is_token_boundary(source, position, token_end):
+            offsets.append(position)
+        position = source.find(_CONTEXTUAL_KEYWORD, position + 1, end)
+    return tuple(offsets)
+
+
+def _is_token_boundary(source: bytes, start: int, end: int) -> bool:
+    before = source[start - 1] if start else None
+    after = source[end] if end < len(source) else None
+    return before != ord("@") and not _identifier_byte(before) and not _identifier_byte(after)
+
+
+def _identifier_byte(value: int | None) -> bool:
+    return value is not None and (value >= 0x80 or value == ord("_") or chr(value).isalnum())
+
+
+def _newline_offsets(source: bytes) -> tuple[int, ...]:
+    return tuple(index for index, value in enumerate(source) if value == ord("\n"))
+
+
+def _is_declaration_identifier(root, offset: int) -> bool:
+    node = root.descendant_for_byte_range(offset, offset + len(_CONTEXTUAL_KEYWORD))
+    if (
+        node.type != "identifier"
+        or node.start_byte != offset
+        or node.end_byte != offset + len(_CONTEXTUAL_KEYWORD)
+        or node.parent is None
+    ):
+        return False
+    field_name = next(
+        (
+            node.parent.field_name_for_child(index)
+            for index, child in enumerate(node.parent.children)
+            if child == node
+        ),
+        None,
+    )
+    return field_name in _NON_EXPRESSION_FIELDS
+
+
+def _has_authorized_role(root, offset: int) -> bool:
+    node = root.descendant_for_byte_range(offset, offset + len(_NEUTRAL_IDENTIFIER))
+    if node.type != "identifier" or node.start_byte != offset or node.end_byte != offset + len(_NEUTRAL_IDENTIFIER):
+        return False
+    parent = node.parent
+    if parent is None:
+        return False
+    if parent.type == "argument" and parent.child_by_field_name("name") == node:
+        return True
+    field_name = next(
+        (parent.field_name_for_child(index) for index, child in enumerate(parent.children) if child == node),
+        None,
+    )
+    return (
+        parent.type.endswith("_expression") or parent.type in _EXPRESSION_CONTAINERS
+    ) and field_name not in _NON_EXPRESSION_FIELDS

{agent_code_guard-0.2.0 → agent_code_guard-0.3.0}/src/agent_code_guard/analysis/errors.py

@@ -4,6 +4,10 @@
 class AnalysisError(RuntimeError):
     """Base error suitable for Code Guard's existing exit-3 boundary."""
 
+    def __init__(self, message: str, *, language: str | None = None) -> None:
+        super().__init__(message)
+        self.language = language
+
 
 class ProviderUnavailableError(AnalysisError):
     """The configured parser provider or a required grammar is unavailable."""

agent_code_guard-0.3.0/src/agent_code_guard/analysis/pipeline.py

@@ -0,0 +1,86 @@
+"""Parse applicable selected files once and return reusable immutable facts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .adapters import extract_facts
+from .csharp_compat import corrected_csharp_root
+from .errors import ProviderUnavailableError, SyntaxAnalysisError
+from .facts import AnalysisFacts, FileFacts
+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:
+    """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))]
+    return AnalysisFacts(tuple(results))
+
+
+@dataclass(frozen=True)
+class UnavailableAnalysis:
+    path: Path
+    language: str
+    kind: str
+    message: str
+
+
+@dataclass(frozen=True)
+class BatchAnalysis:
+    facts: AnalysisFacts
+    unavailable: tuple[UnavailableAnalysis, ...]
+
+
+def analyze_files_for_runner(
+    files: tuple[Path, ...] | list[Path], 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)
+        if not is_applicable(path):
+            continue
+        try:
+            results.append(_analyze_file(path, active_provider))
+        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)))
+    return BatchAnalysis(AnalysisFacts(tuple(results)), tuple(unavailable))
+
+
+def _analyze_file(path: Path, provider: ParserProvider) -> FileFacts:
+    callables = []
+    controls = []
+    decisions = []
+    regions = executable_regions(path, provider)
+    for region in regions:
+        try:
+            tree = provider.parse(region.language, region.source)
+        except (SyntaxAnalysisError, ProviderUnavailableError) as exc:
+            if exc.language is None:
+                raise type(exc)(str(exc), language=region.language) from exc
+            raise
+        root = tree.root_node
+        if tree.root_node.has_error:
+            root = (
+                corrected_csharp_root(provider, region.source, tree)
+                if region.language == "csharp"
+                else None
+            )
+            if root is None:
+                raise SyntaxAnalysisError(
+                    f"unable to parse {path}: embedded {region.language} syntax tree contains errors",
+                    language=region.language,
+                )
+        region_callables, region_controls, region_decisions = extract_facts(root, region)
+        callables.extend(region_callables)
+        controls.extend(region_controls)
+        decisions.extend(region_decisions)
+    return FileFacts(path, tuple(callables), tuple(controls), tuple(decisions), len(regions))

{agent_code_guard-0.2.0 → agent_code_guard-0.3.0}/src/agent_code_guard/analysis/provider.py

@@ -33,13 +33,15 @@ class TreeSitterProvider:
             except (ImportError, LookupError, OSError, RuntimeError) as exc:
                 raise ProviderUnavailableError(
                     f"syntax provider unavailable for supported language {language!r}: {exc}; "
-                    "reinstall Agent Code Guard"
+                    "reinstall Agent Code Guard",
+                    language=language,
                 ) from exc
             self._parsers[language] = parser
         try:
             return parser.parse(source)
-        except Exception as exc:
+        except RuntimeError as exc:
             raise ProviderUnavailableError(
                 f"syntax provider failed for supported language {language!r}: {exc}; "
-                "verify the Agent Code Guard installation"
+                "verify the Agent Code Guard installation",
+                language=language,
             ) from exc

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

@@ -65,7 +65,9 @@ def executable_regions(path: Path, provider: ParserProvider) -> tuple[Executable
 def _vue_regions(path: Path, source: bytes, provider: ParserProvider) -> tuple[ExecutableRegion, ...]:
     root = provider.parse("vue", source).root_node
     if root.has_error:
-        raise SyntaxAnalysisError(f"unable to parse {path}: Vue container syntax tree contains errors")
+        raise SyntaxAnalysisError(
+            f"unable to parse {path}: Vue container syntax tree contains errors", language="vue",
+        )
     regions: list[ExecutableRegion] = []
     for element in root.named_children:
         if element.type != "script_element":
@@ -73,7 +75,9 @@ def _vue_regions(path: Path, source: bytes, provider: ParserProvider) -> tuple[E
         start_tag = next(child for child in element.named_children if child.type == "start_tag")
         attributes = _attributes(start_tag, source)
         if "src" in attributes:
-            raise SyntaxAnalysisError(f"unable to analyze {path}: external Vue script regions are unsupported")
+            raise SyntaxAnalysisError(
+                f"unable to analyze {path}: external Vue script regions are unsupported", language="vue",
+            )
         language = _script_language(path, attributes.get("lang"))
         raw_text = next((child for child in element.named_children if child.type == "raw_text"), None)
         if raw_text is not None:
@@ -106,4 +110,6 @@ def _script_language(path: Path, value: str | None) -> str:
         return "javascript"
     if value in {"ts", "typescript"}:
         return "typescript"
-    raise SyntaxAnalysisError(f"unable to analyze {path}: unsupported Vue script language: {value}")
+    raise SyntaxAnalysisError(
+        f"unable to analyze {path}: unsupported Vue script language: {value}", language="vue",
+    )

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

@@ -17,6 +17,7 @@ from .guards import callable_size, complexity, loc, markdown_document_size, mark
 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 .skill_distribution import export_skill, skill_path as installed_skill_path
 
 DISTRIBUTION_NAME = "agent-code-guard"
@@ -250,13 +251,31 @@ class ScopeSummary:
     analyzed: int
     inapplicable: int
     excluded: int
+    unavailable: int | None = None
 
     def to_json(self) -> dict[str, int]:
-        return {
+        data = {
             "selected": self.selected,
             "analyzed": self.analyzed,
             "inapplicable": self.inapplicable,
-            "excluded": self.excluded,
+        }
+        if self.unavailable is not None:
+            data["unavailable"] = self.unavailable
+        data["excluded"] = self.excluded
+        return data
+
+
+@dataclass(frozen=True)
+class UnavailableEntry:
+    path: str
+    language: str
+    kind: str
+    message: str
+
+    def to_json(self) -> dict[str, str]:
+        return {
+            "path": self.path, "language": self.language,
+            "kind": self.kind, "message": self.message,
         }
 
 
@@ -264,6 +283,8 @@ class ScopeSummary:
 class CompletedAnalysis:
     results: list[GuardResult]
     scope: ScopeSummary
+    unavailable: tuple[UnavailableEntry, ...] = ()
+    incomplete_guard_ids: tuple[str, ...] = ()
 
 
 def payload(
@@ -273,12 +294,28 @@ def payload(
     if isinstance(analysis, list):
         analysis = CompletedAnalysis(analysis, ScopeSummary(0, 0, 0, 0))
     results = analysis.results
+    completed_overall = aggregate_state(results)
+    incomplete = bool(analysis.unavailable)
     data = {
-        "overall": aggregate_state(results),
+        "overall": "incomplete" if incomplete else completed_overall,
         "scope": analysis.scope.to_json(),
         "requiredPolicies": required_policies(results),
         "guards": {result.guard_id: result.to_json() for result in results},
     }
+    if incomplete:
+        data = {
+            "overall": "incomplete",
+            "completedOverall": completed_overall,
+            "scope": data["scope"],
+            "unavailable": [entry.to_json() for entry in analysis.unavailable],
+            "requiredPolicies": data["requiredPolicies"],
+            "guards": data["guards"],
+        }
+        unavailable_paths = [entry.path for entry in analysis.unavailable]
+        for guard_id, guard in data["guards"].items():
+            guard["complete"] = guard_id not in analysis.incomplete_guard_ids
+            if not guard["complete"]:
+                guard["unavailablePaths"] = unavailable_paths
     if json_mode == "compact":
         for guard in data["guards"].values():
             guard["findings"] = [
@@ -321,7 +358,8 @@ def run_analysis(
     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))
-        facts = analysis.analyze_files(scope.files)
+        batch = analysis.analyze_files_for_runner(scope.files)
+        facts = batch.facts
         if callable_size_config.enabled:
             results.append(callable_size.run(scope.root, callable_size_config, facts))
         if nesting_config.enabled:
@@ -345,9 +383,27 @@ def run_analysis(
             results.append(markdown_section_size.run(scope.root, markdown_section_config, _empty_markdown_facts()))
     selected = len(scope.files)
     analyzed = len(analyzed_files)
+    unavailable = tuple(
+        UnavailableEntry(
+            reporting_path(item.path, scope.root), item.language, item.kind, item.message,
+        )
+        for item in (batch.unavailable if needs_analysis else ())
+    )
+    incomplete_guard_ids = tuple(
+        guard_id for guard_id, enabled in (
+            ("callableSize", callable_size_config.enabled),
+            ("nesting", nesting_config.enabled),
+            ("complexity", complexity_config.enabled),
+        ) if enabled and unavailable
+    )
     return CompletedAnalysis(
         results,
-        ScopeSummary(selected, analyzed, selected - analyzed, len(scope.excluded_files)),
+        ScopeSummary(
+            selected, analyzed, selected - analyzed, len(scope.excluded_files),
+            len({entry.path for entry in unavailable}) if unavailable else None,
+        ),
+        unavailable,
+        incomplete_guard_ids,
     )
 
 
@@ -362,6 +418,8 @@ def print_text(data: dict[str, object]) -> None:
 
 
 def exit_code(overall: str, ci: bool) -> int:
+    if overall == "incomplete":
+        return 3
     if overall == "fail":
         return 2
     if overall == "review" and not ci:

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

@@ -26,6 +26,7 @@ REVIEW_GUARD_NAMES = (
 REVIEW_GUARD_KEYS = {"enabled", "reviewAt"}
 LOC_KEYS = {
     "enabled",
+    "ratchetAt",
     "warnAt",
     "failAt",
     "countBlankLines",

{agent_code_guard-0.2.0 → agent_code_guard-0.3.0}/src/agent_code_guard/guards/loc.py

@@ -64,6 +64,7 @@ class Config:
     exclude: list[str]
     allowed_large_files: list[AllowedLargeFile]
     overrides: list[ThresholdOverride]
+    ratchet_at: str = "fail"
 
 
 def load_config(args: argparse.Namespace) -> Config:
@@ -89,6 +90,9 @@ def load_config(args: argparse.Namespace) -> Config:
     enabled = data.get("enabled", True)
     if not isinstance(enabled, bool):
         raise ValueError("guards.loc.enabled must be a boolean")
+    ratchet_at = data.get("ratchetAt", "fail")
+    if not isinstance(ratchet_at, str) or ratchet_at not in {"fail", "review"}:
+        raise ValueError("guards.loc.ratchetAt must be 'fail' or 'review'")
 
     warn_at = args.warn if args.warn is not None else data.get("warnAt", DEFAULT_WARN_AT)
     fail_at = args.fail if args.fail is not None else data.get("failAt", DEFAULT_FAIL_AT)
@@ -114,6 +118,7 @@ def load_config(args: argparse.Namespace) -> Config:
         False if args.ignore_comment_lines else count_comments, include_extensions, exclude,
         parse_allowed_large_files(data.get("allowedLargeFiles", [])),
         parse_overrides(data.get("overrides", [])),
+        ratchet_at,
     )
 
 
@@ -201,6 +206,20 @@ def evaluate(
     ratchet_status = None
     if allowed and counted > warn_at:
         native_status, state, reason = "exempt", "pass", allowed.reason
+    elif config.ratchet_at == "review" and baseline_loc is not None:
+        if counted > baseline_loc:
+            native_status, state = "ratchetExceeded", "fail"
+            reason = f"LOC grew above source-controlled allowance {baseline_loc}."
+            ratchet_status = "exceeded"
+        elif counted > fail_at:
+            native_status, state, reason = "grandfathered", "review", None
+            ratchet_status = "within"
+        elif counted > warn_at:
+            native_status, state, reason = "warn", "review", None
+            ratchet_status = "within"
+        else:
+            native_status, state, reason = "ok", "pass", None
+            ratchet_status = "notNeeded"
     elif counted > fail_at:
         if baseline_loc is not None and counted <= baseline_loc:
             native_status, state, reason = "grandfathered", "review", None

{agent_code_guard-0.2.0 → agent_code_guard-0.3.0}/src/agent_code_guard/human_output.py

@@ -106,10 +106,25 @@ def _markdown_lines(data: dict[str, object]) -> list[str]:
 def format_completed_analysis(data: dict[str, object]) -> str:
     """Return the complete human report for an existing completed payload."""
     scope = data["scope"]
-    lines = [
-        f"{str(data['overall']).upper()}: {scope['selected']} selected; {scope['analyzed']} analyzed; "
-        f"{scope['inapplicable']} inapplicable; {scope['excluded']} excluded."
-    ]
+    if data["overall"] == "incomplete":
+        lines = [
+            f"INCOMPLETE: {scope['selected']} selected; {scope['analyzed']} analyzed; "
+            f"{scope['inapplicable']} inapplicable; {scope['unavailable']} unavailable; "
+            f"{scope['excluded']} excluded. Completed findings: {str(data['completedOverall']).upper()}."
+        ]
+        lines.extend(
+            f"UNAVAILABLE: {item['path']} [{item['language']} {item['kind']}] - {item['message']}"
+            for item in data["unavailable"]
+        )
+        incomplete_guards = [
+            guard_id for guard_id, result in data["guards"].items() if not result["complete"]
+        ]
+        lines.append(f"Incomplete guards: {', '.join(incomplete_guards)}.")
+    else:
+        lines = [
+            f"{str(data['overall']).upper()}: {scope['selected']} selected; {scope['analyzed']} analyzed; "
+            f"{scope['inapplicable']} inapplicable; {scope['excluded']} excluded."
+        ]
     lines.extend(_loc_lines(data))
     lines.extend(_callable_size_lines(data))
     lines.extend(_nesting_lines(data))

{agent_code_guard-0.2.0 → agent_code_guard-0.3.0}/src/agent_code_guard/loc_baseline.py

@@ -126,8 +126,9 @@ def create(root: Path, files: tuple[Path, ...], config: loc.Config) -> int:
         if any(matches_path_glob(relative, item.path) for item in config.allowed_large_files):
             continue
         counted = loc.count_loc(path, config)
-        _, fail_at, _ = loc.effective_thresholds(relative, config)
-        if counted > fail_at:
+        warn_at, fail_at, _ = loc.effective_thresholds(relative, config)
+        threshold = warn_at if config.ratchet_at == "review" else fail_at
+        if counted > threshold:
             entries[relative] = counted
     content = serialize(entries)
     created_directory = not target.parent.exists()
@@ -178,8 +179,9 @@ def update(
             raise ValueError(
                 f"LOC baseline update would increase allowance for {relative}: {allowance} to {counted}"
             )
-        _, fail_at, _ = loc.effective_thresholds(relative, config)
-        if counted <= fail_at:
+        warn_at, fail_at, _ = loc.effective_thresholds(relative, config)
+        threshold = warn_at if config.ratchet_at == "review" else fail_at
+        if counted <= threshold:
             proposed.pop(relative)
             removed += 1
         elif counted < allowance:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-code-guard
-Version: 0.2.0
+Version: 0.3.0
 Summary: Deterministic cross-language guardrails for agent-assisted development
 License-Expression: MIT
 Project-URL: Source, https://github.com/stef-k/agent-code-guard
@@ -82,16 +82,28 @@ environment, uv, and developer alternatives.
 
 Copy this prompt to a coding agent:
 
-> Consult the official Agent Code Guard repository and documentation. Install
-> the published distribution in an isolated supported way, preferably with
-> pipx; verify `code-guard --version` and run `code-guard doctor`. Locate the
-> installed version-matched skill with `code-guard --skill-path`, and use or
-> export only that skill through the documented mechanism. Inspect this
-> repository without creating a LOC baseline and use changed-work scope. Ask
-> before exporting into a persistent skill directory, changing persistent
-> agent or platform configuration, or configuring hooks.
-> Never weaken thresholds, exclusions, configuration, or baselines merely to
-> silence findings.
+> Adopt Agent Code Guard for this repository using the official project and
+> documentation at https://github.com/stef-k/agent-code-guard. This prompt
+> authorizes installing the published distribution in an isolated supported
+> way, preferably with `pipx install agent-code-guard`, and persistently
+> activating or exporting its installed, version-matched skill for the current
+> agent environment. Verify `code-guard --version` and run `code-guard doctor`,
+> then locate the skill with `code-guard --skill-path`. Follow the
+> [skill activation guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md):
+> activate that installed path when the platform supports it, or export it with
+> `code-guard --export-skill <target-directory>` to the platform's documented
+> skill directory. Do not guess a target or overwrite an existing export; verify
+> that `.agent-code-guard-version` matches the installed distribution. Follow the
+> [agent workflow](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md)
+> without creating a LOC baseline. After meaningful source or Markdown edits, run
+> `code-guard . --changed-only --json --json-mode compact`; outside Git, pass the
+> exact edited files. Inspect REVIEW and FAIL findings, make only genuine
+> improvements, rerun the check, and report the result. Never weaken thresholds,
+> exclusions, configuration, or baselines merely to silence findings. Code Guard
+> does not install or enable hooks by default. Ask before configuring a post-edit
+> or post-turn hook, or making unrelated persistent agent or platform changes.
+> Finish by reporting the installed version, doctor status, activated skill
+> location, first analysis result, and any REVIEW findings you accepted.
 
 ## Five-minute start
 
@@ -138,12 +150,14 @@ hook-assisted process.
   warranted; normally exit `1`.
 - **Completed FAIL** — blocks normal completion until fixed or an explicitly
   authorized exception applies; exit `2` with a completed report on stdout.
+- **INCOMPLETE** — one or more requested syntax analyses are unavailable;
+  independent completed findings remain authoritative, but the run exits `3`.
 - An argparse usage or invalid-choice error exits `2`, writes usage/error text
   to stderr, and produces no completed report.
-- Other Code Guard tool, configuration, scope, or provider errors exit `3`.
+- Other Code Guard tool, configuration, scope, or unexpected errors exit `3`.
 
 `--ci` makes REVIEW nonblocking at the process level by changing its exit to
-`0`; it does not hide the findings or change FAIL and tool-error exits.
+`0`; it does not hide findings or change FAIL, INCOMPLETE, and tool-error exits.
 
 **Never game a metric.** Do not create artificial helpers, files,
 abstractions, formatting, exclusions, or policy changes merely to lower a
@@ -175,6 +189,12 @@ result, scope, required policies, guards, ordering, and actionable findings.
 Named modes require `--json`. See [Usage](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md) for the schema and
 option contract.
 
+Known per-file syntax or provider failures instead produce `overall:
+"incomplete"`, ordered structured `unavailable` records, and completed guard
+evidence. Syntax guards identify unavailable paths; LOC and Markdown remain
+complete. Full, debug, and compact JSON retain unavailable records unchanged,
+and completed runs retain their existing schema.
+
 ### Common scope commands
 
 ```bash
@@ -200,7 +220,8 @@ Markdown guards apply to `.md` files.
 Generic `.h` files are not syntax-dispatched; `.markdown` is not enabled; Vue
 template and style regions are not executable syntax input; and unsupported
 artifacts are inapplicable. Malformed applicable syntax or a required provider
-failure is a fail-closed tool error. See [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md).
+failure is unavailable evidence, distinct from both an inapplicable file and a
+completed FAIL finding. See [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md).
 
 ### Skill integration
 
@@ -221,6 +242,9 @@ Built-in defaults require no configuration. Configure a project only for a
 concrete policy reason; see the [configuration guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/configuration.md).
 The LOC baseline is an explicit adoption tool for established legacy
 repositories, not an ordinary-use requirement or a way to silence findings.
+Its default `ratchetAt: "fail"` policy freezes files above `failAt`; choose
+`ratchetAt: "review"` only when every established file above `warnAt` must be
+non-increasing while ordinary findings in that range remain REVIEW.
 
 ## Trust, CI, and platform support
 

{agent_code_guard-0.2.0 → agent_code_guard-0.3.0}/src/agent_code_guard.egg-info/SOURCES.txt

@@ -31,6 +31,7 @@ src/agent_code_guard/analysis/__init__.py
 src/agent_code_guard/analysis/adapters.py
 src/agent_code_guard/analysis/branch_normalization.py
 src/agent_code_guard/analysis/callable_identity.py
+src/agent_code_guard/analysis/csharp_compat.py
 src/agent_code_guard/analysis/errors.py
 src/agent_code_guard/analysis/facts.py
 src/agent_code_guard/analysis/language_specs.py

agent_code_guard-0.2.0/src/agent_code_guard/analysis/pipeline.py

@@ -1,37 +0,0 @@
-"""Parse applicable selected files once and return reusable immutable facts."""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from .adapters import extract_facts
-from .errors import SyntaxAnalysisError
-from .facts import AnalysisFacts, FileFacts
-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:
-    """Analyze only applicable entries from the already-resolved caller scope."""
-    active_provider = provider or TreeSitterProvider()
-    results: list[FileFacts] = []
-    for path in files:
-        path = Path(path)
-        if not is_applicable(path):
-            continue
-        callables = []
-        controls = []
-        decisions = []
-        regions = executable_regions(path, active_provider)
-        for region in regions:
-            tree = active_provider.parse(region.language, region.source)
-            if tree.root_node.has_error:
-                raise SyntaxAnalysisError(
-                    f"unable to parse {path}: embedded {region.language} syntax tree contains errors"
-                )
-            region_callables, region_controls, region_decisions = extract_facts(tree.root_node, region)
-            callables.extend(region_callables)
-            controls.extend(region_controls)
-            decisions.extend(region_decisions)
-        results.append(FileFacts(path, tuple(callables), tuple(controls), tuple(decisions), len(regions)))
-    return AnalysisFacts(tuple(results))