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

agent_code_guard-0.2.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: agent-code-guard
+Version: 0.2.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:
+
+> 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.
+
+## 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.
+- 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`.
+
+`--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.
+
+**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.
+
+### 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 a fail-closed tool error. 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.
+
+## 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.2.0/README.md

@@ -0,0 +1,238 @@
+# 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:
+
+> 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.
+
+## 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.
+- 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`.
+
+`--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.
+
+**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.
+
+### 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 a fail-closed tool error. 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.
+
+## 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.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-code-guard"
-version = "0.1.0"
+version = "0.2.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.2.0}/skills/code-guard/SKILL.md

@@ -29,10 +29,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
@@ -53,10 +55,11 @@ 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.
 
-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 +75,8 @@ 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. 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 +90,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 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.