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

agent_code_guard-0.3.0/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: agent-code-guard
+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
+Project-URL: Issues, https://github.com/stef-k/agent-code-guard/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tree-sitter==0.26.0
+Requires-Dist: tree-sitter-language-pack==1.14.3
+Dynamic: license-file
+
+# Agent Code Guard
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/stef-k/agent-code-guard/main/assets/agent-code-guard-mark.svg" width="180" alt="Agent Code Guard project mark">
+</p>
+
+Deterministic maintainability guardrails for source code and Markdown changed by
+a human or coding agent.
+
+[![Production Analysis](https://github.com/stef-k/agent-code-guard/actions/workflows/analysis.yml/badge.svg)](https://github.com/stef-k/agent-code-guard/actions/workflows/analysis.yml)
+[![PyPI](https://img.shields.io/pypi/v/agent-code-guard?logo=pypi&logoColor=white)](https://pypi.org/project/agent-code-guard/)
+[![Python 3.10–3.14](https://img.shields.io/badge/Python-3.10%E2%80%933.14-3776AB?logo=python&logoColor=white)](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/stef-k/agent-code-guard/blob/main/LICENSE)
+
+Agent Code Guard measures file size, callable size, structural nesting,
+cyclomatic complexity, Markdown document size, and Markdown section size. It
+reports deterministic **PASS**, **REVIEW**, or **FAIL** results without
+rewriting your files.
+
+It complements rather than replaces tests, compilers, linters, formatters,
+security tools, and design judgment.
+
+## Why it is useful
+
+Code Guard surfaces files and callables that are becoming difficult to review,
+deep nesting and complex decision logic, and Markdown specifications that are
+losing navigability. It gives humans and agents the same repeatable review
+point after edits and can prevent silent LOC growth beyond an explicit project
+policy.
+
+### What humans gain
+
+- Consistent signals across supported languages and Markdown, whether a change
+  came from a person or an agent.
+- A shared PASS/REVIEW/FAIL vocabulary: continue, inspect with judgment, or
+  block pending correction or an authorized exception.
+- The same checks locally and in CI, with no configuration required for
+  ordinary use and no automatic source mutation.
+
+### What agents gain
+
+- Deterministic feedback after edits and consistent process exits.
+- Changed-file scope instead of unnecessary full-repository scans.
+- Compact JSON that omits normalized pass noise while retaining actionable
+  findings and result structure.
+- Named required policies, so only relevant guidance needs to be loaded, plus a
+  version-matched bundled skill with REVIEW-judgment and anti-gaming rules.
+
+This workflow is designed to reduce unnecessary output and policy loading. It
+still requires the source context needed to understand and judge each finding;
+it makes no claim about measured token savings.
+
+## Installation
+
+[pipx](https://pipx.pypa.io/) isolates the command from project environments:
+
+```bash
+pipx install agent-code-guard
+code-guard --version
+code-guard doctor
+```
+
+`--version` confirms the installed distribution identity. `doctor` checks the
+active installation's health. See the [usage guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md) for virtual
+environment, uv, and developer alternatives.
+
+### Ask your agent to adopt it
+
+Copy this prompt to a coding agent:
+
+> 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
+
+From a Git worktree, inspect the current change:
+
+```bash
+code-guard . --changed-only
+```
+
+Git supplies the changed candidates; every enabled and applicable guard runs.
+No configuration is needed. A REVIEW asks for inspection and judgment, not an
+automatic refactor. Outside Git, pass the exact edited files instead, such as
+`code-guard src/app.py docs/guide.md`.
+
+See the [agent workflow guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md) for repeated human and
+agent use.
+
+## Recommended workflow
+
+```text
+edit supported code or Markdown
+        ↓
+run Code Guard on changed scope
+        ↓
+PASS → continue
+REVIEW → inspect, justify or genuinely improve
+FAIL → fix or obtain an explicitly authorized exception
+        ↓
+rerun
+        ↓
+report the result before completion
+```
+
+Use `code-guard . --changed-only --json --json-mode compact` for a structured,
+low-noise manual agent check. Hooks are optional, platform-owned, and require
+user authorization; Code Guard does not install them. The
+[workflow guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md) owns the complete manual and
+hook-assisted process.
+
+## Interpreting results
+
+- **PASS** — no special action; exit `0`.
+- **REVIEW** — inspect and decide whether genuine structural improvement is
+  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 unexpected errors exit `3`.
+
+`--ci` makes REVIEW nonblocking at the process level by changing its exit to
+`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
+measurement. A REVIEW is not proof of a defect or a mandatory refactor.
+
+## Guard reference
+
+| Guard | Default |
+| --- | --- |
+| File LOC | REVIEW >400, FAIL >600 |
+| Callable size | REVIEW >80 physical LOC |
+| Structural nesting | REVIEW >4 |
+| Cyclomatic complexity | REVIEW >15 |
+| Markdown document size | REVIEW >800 physical lines |
+| Markdown direct-section size | REVIEW >200 physical lines |
+
+Comparisons are strictly greater-than, so equality passes. All guards except
+file LOC are REVIEW-only; only file LOC can FAIL. A new guard must provide
+distinct, deterministic value rather than duplicate conventional tooling. See
+[Guard admission](https://github.com/stef-k/agent-code-guard/blob/main/docs/guard-admission.md).
+
+### Result and JSON reference
+
+Every completed analysis reports selected, analyzed, inapplicable, and
+all-guard-excluded file counts. Bare `--json` is the compatible full output;
+`--json-mode debug` is byte-identical for the same completed invocation, while
+`--json-mode compact` removes only normalized `pass` findings and retains the
+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
+# Current Git work
+code-guard . --changed-only
+
+# Pull request or branch comparison
+code-guard . --base-ref origin/main --ci
+
+# Deliberate full audit
+code-guard .
+```
+
+The base ref must exist in the chosen environment. Changed work is not a full
+audit; do not repeatedly scan unrelated files after every edit.
+
+### Supported languages and formats
+
+Syntax guards support Python, Go, Kotlin, C#, Java, JavaScript, TypeScript, JSX,
+TSX, Vue JavaScript/TypeScript script regions, C++, Rust, PHP, Swift, and Dart.
+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 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
+
+An installed distribution includes the matching Code Guard skill payload:
+
+```bash
+code-guard --skill-path
+code-guard --export-skill <target-directory>
+```
+
+Skill activation is platform-specific and is not performed by pipx or Code
+Guard. See [Skill distribution](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md). The checkout
+compatibility runner is for repository development, not normal installation.
+
+### Configuration
+
+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
+
+CI installs Agent Code Guard and analyzes its own real checkout. REVIEW findings
+remain visible but non-blocking, while FAIL findings and tool errors block the
+workflow; the repository intentionally uses no LOC baseline.
+
+The maintained interpreter range is **CPython 3.10–3.14**. See
+[Platform support](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md) for supported binary platforms and
+source-build boundaries.
+
+## Documentation
+
+- [Documentation index](https://github.com/stef-k/agent-code-guard/blob/main/docs/README.md)
+- [Agent workflow](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md)
+- [Usage and CLI reference](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md)
+- [Configuration](https://github.com/stef-k/agent-code-guard/blob/main/docs/configuration.md)
+- [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md)
+- [Platform support](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md)
+- [Skill distribution](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md)
+
+## Feedback, security, and license
+
+Report defects through the [bug report form](https://github.com/stef-k/agent-code-guard/issues/new?template=bug-report.md),
+propose measurements through the [candidate guard form](https://github.com/stef-k/agent-code-guard/issues/new?template=candidate-guard.md),
+and follow the [security policy](https://github.com/stef-k/agent-code-guard/blob/main/SECURITY.md) for vulnerabilities.
+
+Agent Code Guard grew from the Agent LOC Guard prototype and is now the
+canonical implementation. Licensed under the [MIT License](https://github.com/stef-k/agent-code-guard/blob/main/LICENSE).

agent_code_guard-0.3.0/README.md

@@ -0,0 +1,262 @@
+# Agent Code Guard
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/stef-k/agent-code-guard/main/assets/agent-code-guard-mark.svg" width="180" alt="Agent Code Guard project mark">
+</p>
+
+Deterministic maintainability guardrails for source code and Markdown changed by
+a human or coding agent.
+
+[![Production Analysis](https://github.com/stef-k/agent-code-guard/actions/workflows/analysis.yml/badge.svg)](https://github.com/stef-k/agent-code-guard/actions/workflows/analysis.yml)
+[![PyPI](https://img.shields.io/pypi/v/agent-code-guard?logo=pypi&logoColor=white)](https://pypi.org/project/agent-code-guard/)
+[![Python 3.10–3.14](https://img.shields.io/badge/Python-3.10%E2%80%933.14-3776AB?logo=python&logoColor=white)](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/stef-k/agent-code-guard/blob/main/LICENSE)
+
+Agent Code Guard measures file size, callable size, structural nesting,
+cyclomatic complexity, Markdown document size, and Markdown section size. It
+reports deterministic **PASS**, **REVIEW**, or **FAIL** results without
+rewriting your files.
+
+It complements rather than replaces tests, compilers, linters, formatters,
+security tools, and design judgment.
+
+## Why it is useful
+
+Code Guard surfaces files and callables that are becoming difficult to review,
+deep nesting and complex decision logic, and Markdown specifications that are
+losing navigability. It gives humans and agents the same repeatable review
+point after edits and can prevent silent LOC growth beyond an explicit project
+policy.
+
+### What humans gain
+
+- Consistent signals across supported languages and Markdown, whether a change
+  came from a person or an agent.
+- A shared PASS/REVIEW/FAIL vocabulary: continue, inspect with judgment, or
+  block pending correction or an authorized exception.
+- The same checks locally and in CI, with no configuration required for
+  ordinary use and no automatic source mutation.
+
+### What agents gain
+
+- Deterministic feedback after edits and consistent process exits.
+- Changed-file scope instead of unnecessary full-repository scans.
+- Compact JSON that omits normalized pass noise while retaining actionable
+  findings and result structure.
+- Named required policies, so only relevant guidance needs to be loaded, plus a
+  version-matched bundled skill with REVIEW-judgment and anti-gaming rules.
+
+This workflow is designed to reduce unnecessary output and policy loading. It
+still requires the source context needed to understand and judge each finding;
+it makes no claim about measured token savings.
+
+## Installation
+
+[pipx](https://pipx.pypa.io/) isolates the command from project environments:
+
+```bash
+pipx install agent-code-guard
+code-guard --version
+code-guard doctor
+```
+
+`--version` confirms the installed distribution identity. `doctor` checks the
+active installation's health. See the [usage guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md) for virtual
+environment, uv, and developer alternatives.
+
+### Ask your agent to adopt it
+
+Copy this prompt to a coding agent:
+
+> 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
+
+From a Git worktree, inspect the current change:
+
+```bash
+code-guard . --changed-only
+```
+
+Git supplies the changed candidates; every enabled and applicable guard runs.
+No configuration is needed. A REVIEW asks for inspection and judgment, not an
+automatic refactor. Outside Git, pass the exact edited files instead, such as
+`code-guard src/app.py docs/guide.md`.
+
+See the [agent workflow guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md) for repeated human and
+agent use.
+
+## Recommended workflow
+
+```text
+edit supported code or Markdown
+        ↓
+run Code Guard on changed scope
+        ↓
+PASS → continue
+REVIEW → inspect, justify or genuinely improve
+FAIL → fix or obtain an explicitly authorized exception
+        ↓
+rerun
+        ↓
+report the result before completion
+```
+
+Use `code-guard . --changed-only --json --json-mode compact` for a structured,
+low-noise manual agent check. Hooks are optional, platform-owned, and require
+user authorization; Code Guard does not install them. The
+[workflow guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md) owns the complete manual and
+hook-assisted process.
+
+## Interpreting results
+
+- **PASS** — no special action; exit `0`.
+- **REVIEW** — inspect and decide whether genuine structural improvement is
+  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 unexpected errors exit `3`.
+
+`--ci` makes REVIEW nonblocking at the process level by changing its exit to
+`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
+measurement. A REVIEW is not proof of a defect or a mandatory refactor.
+
+## Guard reference
+
+| Guard | Default |
+| --- | --- |
+| File LOC | REVIEW >400, FAIL >600 |
+| Callable size | REVIEW >80 physical LOC |
+| Structural nesting | REVIEW >4 |
+| Cyclomatic complexity | REVIEW >15 |
+| Markdown document size | REVIEW >800 physical lines |
+| Markdown direct-section size | REVIEW >200 physical lines |
+
+Comparisons are strictly greater-than, so equality passes. All guards except
+file LOC are REVIEW-only; only file LOC can FAIL. A new guard must provide
+distinct, deterministic value rather than duplicate conventional tooling. See
+[Guard admission](https://github.com/stef-k/agent-code-guard/blob/main/docs/guard-admission.md).
+
+### Result and JSON reference
+
+Every completed analysis reports selected, analyzed, inapplicable, and
+all-guard-excluded file counts. Bare `--json` is the compatible full output;
+`--json-mode debug` is byte-identical for the same completed invocation, while
+`--json-mode compact` removes only normalized `pass` findings and retains the
+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
+# Current Git work
+code-guard . --changed-only
+
+# Pull request or branch comparison
+code-guard . --base-ref origin/main --ci
+
+# Deliberate full audit
+code-guard .
+```
+
+The base ref must exist in the chosen environment. Changed work is not a full
+audit; do not repeatedly scan unrelated files after every edit.
+
+### Supported languages and formats
+
+Syntax guards support Python, Go, Kotlin, C#, Java, JavaScript, TypeScript, JSX,
+TSX, Vue JavaScript/TypeScript script regions, C++, Rust, PHP, Swift, and Dart.
+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 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
+
+An installed distribution includes the matching Code Guard skill payload:
+
+```bash
+code-guard --skill-path
+code-guard --export-skill <target-directory>
+```
+
+Skill activation is platform-specific and is not performed by pipx or Code
+Guard. See [Skill distribution](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md). The checkout
+compatibility runner is for repository development, not normal installation.
+
+### Configuration
+
+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
+
+CI installs Agent Code Guard and analyzes its own real checkout. REVIEW findings
+remain visible but non-blocking, while FAIL findings and tool errors block the
+workflow; the repository intentionally uses no LOC baseline.
+
+The maintained interpreter range is **CPython 3.10–3.14**. See
+[Platform support](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md) for supported binary platforms and
+source-build boundaries.
+
+## Documentation
+
+- [Documentation index](https://github.com/stef-k/agent-code-guard/blob/main/docs/README.md)
+- [Agent workflow](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md)
+- [Usage and CLI reference](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md)
+- [Configuration](https://github.com/stef-k/agent-code-guard/blob/main/docs/configuration.md)
+- [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md)
+- [Platform support](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md)
+- [Skill distribution](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md)
+
+## Feedback, security, and license
+
+Report defects through the [bug report form](https://github.com/stef-k/agent-code-guard/issues/new?template=bug-report.md),
+propose measurements through the [candidate guard form](https://github.com/stef-k/agent-code-guard/issues/new?template=candidate-guard.md),
+and follow the [security policy](https://github.com/stef-k/agent-code-guard/blob/main/SECURITY.md) for vulnerabilities.
+
+Agent Code Guard grew from the Agent LOC Guard prototype and is now the
+canonical implementation. Licensed under the [MIT License](https://github.com/stef-k/agent-code-guard/blob/main/LICENSE).

{agent_code_guard-0.1.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.1.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.1.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
 
@@ -29,10 +30,12 @@ Code Guard provides deterministic measurements that act as anchors for agent jud
 
 ## Workflow
 
-With Git, run the installed Code Guard command after supported code or Markdown documentation edits:
+After each meaningful turn that edits supported source code or Markdown, run
+the installed Code Guard command. In Git, prefer changed-work scope and compact
+JSON when structured, low-noise output helps:
 
 ```bash
-code-guard . --changed-only
+code-guard . --changed-only --json --json-mode compact
 ```
 
 An installed Agent Code Guard distribution provides both the command and this
@@ -48,15 +51,17 @@ 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 or another VCS that can provide changed scope, pass exactly the files you created or modified. You are responsible for supplying the complete edited-file set:
+Without Git, pass exactly the files you created or modified. You are
+responsible for supplying the complete edited-file set:
 
 ```bash
-code-guard src/Foo.py src/Bar.ts docs/guide.md
+code-guard src/Foo.py src/Bar.ts docs/guide.md --json --json-mode compact
 ```
 
 Do not create a manifest or temporary scope file. Specific positional files mean “inspect these artifacts.” A directory or `.` means a deliberate recursive audit when no Git selector is used. Positional files/directories bound the candidates selected by `--changed-only`, `--staged`, or `--base-ref`; Git selection fails outside a Git repository and never falls back to an audit.
@@ -72,7 +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.
 
-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.
 
@@ -86,6 +93,24 @@ Policy references:
 
 Do not load unrelated guard policies merely because they exist.
 
+After a genuine correction, rerun Code Guard. Report every accepted REVIEW
+honestly with its justification, and run a final check over the complete
+changed scope before declaring completion.
+
+Agent Code Guard does not install or manage hooks. If the agent platform
+supports a post-edit or post-turn hook, the user has authorized persistent
+configuration, and visible output is retained, the hook may use:
+
+```bash
+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 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
 
 Code Guard is intentionally limited to deterministic concerns that are broadly applicable across conventional programming languages.

{agent_code_guard-0.1.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.