From 0e1406a4d8e5fc0f8c69e4fdff14e471dceaca30 Mon Sep 17 00:00:00 2001 From: Stef Kariotidis Date: Thu, 27 Aug 2026 00:48:48 +0300 Subject: [PATCH 1/6] WIP: start 0.2.0 release preparation (checkpoint) --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 7f35b73..082f344 100644 --- a/pyproject.toml +++ b/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" From ff67f3398bc450a4f75ea92a1e179292e9a3e801 Mon Sep 17 00:00:00 2001 From: Stef Kariotidis Date: Thu, 27 Aug 2026 00:49:22 +0300 Subject: [PATCH 2/6] Finalize 0.2.0 changelog --- CHANGELOG.md | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f7bd3bf..01c326f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,17 +4,24 @@ Notable changes to Agent Code Guard are recorded here. ## Unreleased +## 0.2.0 - 2026-08-27 + ### Added -- Zero-baseline CI dogfooding through the installed console command, with visible - non-blocking REVIEW findings and blocking FAIL findings or tool errors. -- Source-controlled, non-increasing LOC ratchet creation, automatic analysis, - and explicit lowering/pruning for established legacy repositories. +- Zero-baseline CI dogfooding through the installed console command, with no + baseline for this repository, visible non-blocking REVIEW findings under + `--ci`, and blocking FAIL findings or tool errors. +- Source-controlled, non-increasing LOC ratchet creation, automatic read-only + analysis, and explicit lowering/pruning for established legacy repositories; + new projects and this repository should use a zero baseline. - Read-only `code-guard doctor` human and JSON diagnostics for the active installation, bundled skill, configuration, Git context, and parser providers. -- Compact and explicit debug completed-analysis JSON serialization modes while - preserving bare `--json` compatibility. +- Compact and explicit debug completed-analysis JSON serialization modes: + bare `--json` remains the compatible full form, debug is byte-identical for + the same completed invocation, and compact removes only normalized pass + findings while preserving actionable findings and result structure. - Deterministic `code-guard --version` reporting from installed distribution metadata, with human and JSON output modes. - Concise selected, analyzed, inapplicable, and all-guard-excluded file counts - in every completed human and JSON analysis result. + in every completed human and JSON analysis result, where analyzed plus + inapplicable equals selected and excluded files are disjoint. From 4b268c83280f9930b6d26cbc950767f0995002fd Mon Sep 17 00:00:00 2001 From: Stef Kariotidis Date: Thu, 27 Aug 2026 18:17:34 +0300 Subject: [PATCH 3/6] WIP: add first-use and agent workflow documentation (checkpoint) --- README.md | 297 ++++++++++++++++++++--------------------- docs/README.md | 1 + docs/agent-workflow.md | 112 ++++++++++++++++ 3 files changed, 261 insertions(+), 149 deletions(-) create mode 100644 docs/agent-workflow.md diff --git a/README.md b/README.md index 6c521c0..774c92d 100644 --- a/README.md +++ b/README.md @@ -4,84 +4,135 @@ Agent Code Guard project mark

-Deterministic guardrails for agent-assisted software development. +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) -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. +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. -Code Guard gives coding agents objective measurements and **PASS / REVIEW / -FAIL** signals while leaving design decisions to agent and user judgment. +It complements rather than replaces tests, compilers, linters, formatters, +security tools, and design judgment. -```text -deterministic measurement - ↓ -PASS / REVIEW / FAIL - ↓ -agent 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/) keeps the command isolated from project -environments: +[pipx](https://pipx.pypa.io/) isolates the command from project environments: ```bash pipx install agent-code-guard +code-guard --version +code-guard doctor ``` -See the [usage guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md) -for a virtual-environment alternative and developer installation. +`--version` confirms the installed distribution identity. `doctor` checks the +active installation's health. See the [usage guide](docs/usage.md) for virtual +environment, uv, and developer alternatives. + +### Ask your agent to adopt it -## Quick start +Copy this prompt to a coding agent: -Run all enabled, applicable guards over your current Git work: +> 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 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 determines the edited-file candidates, Code Guard applies every enabled -and applicable guard, and project or user exclusions remain authoritative. No -configuration file is required. +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`. -## Result model +See the [agent workflow guide](docs/agent-workflow.md) for repeated human and +agent use. -Every completed analysis begins with a concise file-scope summary: +## Recommended workflow ```text -PASS: 3 selected; 2 analyzed; 1 inapplicable; 0 excluded. +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 ``` -The state is `PASS`, `REVIEW`, or `FAIL`. JSON output adds the same counts as a -top-level `scope` object without changing `overall`, `requiredPolicies`, or -`guards`: - -```json -"scope": { - "selected": 3, - "analyzed": 2, - "inapplicable": 1, - "excluded": 0 -} -``` +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](docs/agent-workflow.md) owns the complete manual and +hook-assisted process. -- **PASS** — no special action. -- **REVIEW** — inspect the finding and decide whether meaningful improvement is - warranted. REVIEW is not automatic refactoring. +## Interpreting results + +- **PASS** — no special action; exit `0`. +- **REVIEW** — inspect and decide whether genuine structural improvement is + warranted; normally exit `1`. - **FAIL** — blocks normal completion until fixed or an explicitly authorized - exception applies. + exception applies; exit `2`. +- A tool, invocation, configuration, scope, or provider error exits `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 the metric.** Preserve clarity and useful structure; do not create -artificial helpers, files, abstractions, formatting, or exclusions merely to -lower a measurement. +**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. -## Default guards +## Guard reference | Guard | Default | | --- | --- | @@ -93,144 +144,92 @@ lower a measurement. | 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. +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](docs/guard-admission.md). -Agent Code Guard intentionally remains small. A new guard must provide distinct, -deterministic agent-guardrail value rather than merely duplicate mature -conventional tooling. See [Guard admission](https://github.com/stef-k/agent-code-guard/blob/main/docs/guard-admission.md). +### Result and JSON reference -## Common workflows +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](docs/usage.md) for the schema and +option contract. -Normal Git work: +### Common scope commands ```bash +# Current Git work code-guard . --changed-only -``` -Explicit agent-owned scope without Git: - -```bash -code-guard src/Foo.py src/Bar.ts docs/guide.md -``` - -Pull request or branch comparison: - -```bash +# Pull request or branch comparison code-guard . --base-ref origin/main --ci -``` - -Bare `--json` remains the compatible full completed-analysis output. For -routine agent checks, add `--json-mode compact` to omit normalized `pass` -findings while retaining actionable `review` and `fail` findings. Use -`--json-mode debug` as the explicit full-output form when investigating all -measurements. Both named modes require `--json`; no detail mode exists. - -The actual base ref must exist or be fetched correctly in the chosen CI -environment. - -Deliberate full audit: -```bash +# Deliberate full audit code-guard . ``` -Confirm the installed distribution identity without running analysis: - -```text -$ code-guard --version -agent-code-guard -``` - -Use `code-guard --version --json` for the exact JSON shape -`{"distribution": "agent-code-guard", "version": ""}`. The version -comes from installed `agent-code-guard` distribution metadata. Version mode may -be combined only with `--json`. Both successful version forms exit `0`; -incompatible arguments or unavailable metadata are tool errors that exit `3` -through the normal human or JSON error channel. - -Changed work is not a full audit. Use Git selection during normal development; -do not repeatedly scan unrelated repository history after every edit. +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 +### 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. -Important boundaries: +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](docs/language-support.md). -- Generic `.h` files are not syntax-dispatched because their language context - is ambiguous. -- `.markdown` is not currently enabled for Markdown guards. -- Vue template and style regions are not executable syntax input. -- Unsupported artifacts are simply inapplicable. -- Malformed applicable syntax or a required provider failure is a fail-closed - tool error, never heuristic partial analysis. +### Skill integration -See [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md) -for extension and mixed-content details. - -## Agent integration - -CLI-only use requires no skill export. Each installed distribution also carries -a version-matched Code Guard skill payload for agent workflows: +An installed distribution includes the matching Code Guard skill payload: ```bash code-guard --skill-path code-guard --export-skill ``` -See [Skill distribution](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md) -for discovery, export, and integration guarantees. The checkout compatibility -runner is for repository and skill compatibility, not primary end-user -installation. +Skill activation is platform-specific and is not performed by pipx or Code +Guard. See [Skill distribution](docs/skill-distribution.md). The checkout +compatibility runner is for repository development, not normal installation. -## Configuration +### Configuration -Built-in defaults require no config. A minimal project configuration is: - -```json -{ - "version": 1 -} -``` - -Use configuration only when a project has a concrete policy reason to change a -guard or scope. See the [Configuration guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/configuration.md). - -## Documentation +Built-in defaults require no configuration. Configure a project only for a +concrete policy reason; see the [configuration guide](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. -- [Documentation index](https://github.com/stef-k/agent-code-guard/blob/main/docs/README.md) -- [Usage](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) +## Trust, CI, and platform support -## Platform support - -The maintained interpreter range is **CPython 3.10–3.14**. The normal binary -installation envelope is: +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. -- Windows x86-64 and ARM64; -- macOS x86-64 and ARM64; -- Linux glibc 2.34 or newer on x86-64 and ARM64. +The maintained interpreter range is **CPython 3.10–3.14**. See +[Platform support](docs/platform-support.md) for supported binary platforms and +source-build boundaries. -Source builds outside that binary envelope are best effort and are not -release-supported. See [Platform support](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md) -for exact wheel and deployment boundaries. +## Documentation -## Feedback and security +- [Documentation index](docs/README.md) +- [Agent workflow](docs/agent-workflow.md) +- [Usage and CLI reference](docs/usage.md) +- [Configuration](docs/configuration.md) +- [Language support](docs/language-support.md) +- [Platform support](docs/platform-support.md) +- [Skill distribution](docs/skill-distribution.md) -Report normal defects through the [bug report form](https://github.com/stef-k/agent-code-guard/issues/new?template=bug-report.md) -and propose new measurements through the [Candidate guard form](https://github.com/stef-k/agent-code-guard/issues/new?template=candidate-guard.md). -For vulnerability reporting, follow the repository [Security policy](https://github.com/stef-k/agent-code-guard/blob/main/SECURITY.md). +## Feedback, security, and license -## Background 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](SECURITY.md) for vulnerabilities. Agent Code Guard grew from the Agent LOC Guard prototype and is now the -canonical implementation. It remains focused on deterministic measurements -that complement—not replace—tests, compilers, formatters, linters, security -tools, or design judgment. - -Licensed under the [MIT License](https://github.com/stef-k/agent-code-guard/blob/main/LICENSE). +canonical implementation. Licensed under the [MIT License](LICENSE). diff --git a/docs/README.md b/docs/README.md index d29c676..14f4e49 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,6 +5,7 @@ contract and the evidence behind it. ## User guides +- [Human and agent workflow](agent-workflow.md) — installation, repeated changed-work checks, REVIEW judgment, and optional authorized hooks. - [Usage](usage.md) — installation, file selection, output, result states, and CI. - [Configuration](configuration.md) — zero-config defaults, guard settings, and exclusions. - [Language support](language-support.md) — applicable syntax languages, extensions, and mixed-content behavior. diff --git a/docs/agent-workflow.md b/docs/agent-workflow.md new file mode 100644 index 0000000..bb56703 --- /dev/null +++ b/docs/agent-workflow.md @@ -0,0 +1,112 @@ +# Human and agent workflow + +This guide owns the repeated-use workflow for Agent Code Guard. The +[usage guide](usage.md) remains the CLI reference, and +[skill distribution](skill-distribution.md) explains skill discovery and +activation. + +## Human setup and decisions + +Install the published command in an isolated environment and verify the active +installation: + +```bash +pipx install agent-code-guard +code-guard --version +code-guard doctor +``` + +Ask your coding agent to locate the bundled version-matched skill with +`code-guard --skill-path` and adopt the workflow below without creating a LOC +baseline. Decide whether checks remain manual or use an optional platform hook. +Exporting a skill into a persistent directory, installing a hook, or changing +persistent user or repository configuration requires your authorization. + +Require the agent to report its final result and any REVIEW findings it accepts +with justification. Use CI as the final gate, not as a substitute for checks +during development. + +## The shared loop + +```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 +``` + +After each meaningful turn that changes supported source code or Markdown, the +agent runs Code Guard. It inspects every REVIEW and FAIL, loads only policies +named by the result, and refactors only when doing so improves real structure. +It must never split code mechanically or weaken thresholds, exclusions, +configuration, or baselines to silence a measurement. After relevant +corrections it reruns the check, and it always runs a final check before +declaring completion. + +PASS means continue. REVIEW means inspect and either make a genuine improvement +or retain the code with an honest justification; it is not automatically a +defect. FAIL blocks normal completion until corrected or covered by an +explicitly authorized policy exception. Tool or invocation errors mean the +analysis did not complete. + +## Manual agent loop + +In a Git repository, prefer changed-work scope and compact JSON when structured, +low-noise output helps: + +```bash +code-guard . --changed-only --json --json-mode compact +``` + +Git supplies staged, unstaged, and untracked candidates within the positional +bounds. The process exits are exact: + +- PASS: `0` +- REVIEW: `1` +- FAIL: `2` +- tool or invocation error: `3` + +The agent inspects REVIEW and FAIL findings, applies judgment, loads only the +named required policies, and reruns after relevant correction. + +Git selection requires a Git repository and fails instead of silently becoming +a recursive audit. Outside Git, pass the exact edited files: + +```bash +code-guard path/to/edited.py docs/edited.md --json --json-mode compact +``` + +Do not recursively scan the whole tree after every turn. + +## Optional hook-assisted loop + +Agent Code Guard does not install or manage hooks. If the coding-agent platform +supports a post-edit or post-turn hook, and the user authorizes the persistent +configuration change, that platform may invoke: + +```bash +code-guard . --changed-only --ci --json --json-mode compact +``` + +`--ci` changes only REVIEW's process exit from `1` to `0`. REVIEW findings +remain visible and require inspection; FAIL remains `2`, and tool or invocation +errors remain `3`. Hook output must not be suppressed. + +Hook syntax and configuration paths are platform-specific. The agent must +consult its platform's own documentation; no universal hook configuration is +implied. Outside Git, the integration must supply the exact edited files. + +## Completion and CI + +Before completion, rerun Code Guard on the complete changed scope. Report the +aggregate result, any FAIL or tool errors, and each accepted REVIEW with its +reason. Then use the repository's CI integration as the final gate. Humans +remain responsible for deciding whether accepted REVIEW pressure warrants +follow-up work and for authorizing exceptions or persistent integrations. From 9dc4231473ce47a7ed44a4c12240cf38dcd83be5 Mon Sep 17 00:00:00 2001 From: Stef Kariotidis Date: Thu, 27 Aug 2026 18:18:26 +0300 Subject: [PATCH 4/6] Document installed agent workflow and skill activation --- docs/skill-distribution.md | 97 +++++++++++++++++++++----------------- docs/usage.md | 19 ++++++-- skills/code-guard/SKILL.md | 32 +++++++++++-- 3 files changed, 97 insertions(+), 51 deletions(-) diff --git a/docs/skill-distribution.md b/docs/skill-distribution.md index ec37b26..662018d 100644 --- a/docs/skill-distribution.md +++ b/docs/skill-distribution.md @@ -1,45 +1,58 @@ # Code Guard skill distribution The `agent-code-guard` Python distribution is the single versioned release -unit. A pip, pipx, or uv tool installation receives the `code-guard` command, -its runtime, and an inert canonical Code Guard skill payload from the same -artifact version. Installation does not inspect or modify any agent directory -or configuration. Installing `agent-code-guard` through pip, pipx, or uv -provides the command, runtime, and exact version-matched skill payload. - -CLI-only use is fully supported. Install the Python distribution and run, for -example, `code-guard . --changed-only`. The bundled skill does not affect -startup, scope, configuration, parser loading, findings, or exit behavior, and -it never needs to be exported for CLI-only use. - -For skill-and-CLI use: - -1. Install the Python distribution by the normal pip, pipx, or uv tool flow. -2. Run `code-guard --skill-path` to print the absolute path of that installed - distribution's exact skill payload, or run - `code-guard --export-skill ` to copy it into exactly the - supplied directory. -3. Register or install that directory using the chosen agent system's own - mechanism. Agent-specific destinations and configuration are outside Code - Guard's responsibility. -4. The skill invokes the installed `code-guard` command. - -`--skill-path` performs no project discovery, configuration loading, Git work, -or guard execution. `--export-skill` has the same isolation, creates a missing -target, and rejects an existing non-empty target instead of overwriting it. It -copies only `SKILL.md`, `LICENSE.txt`, `agents/openai.yaml`, and the policy files -under `references/`; the checkout-only `scripts/code_guard.py` compatibility -runner is deliberately excluded. - -For read-only troubleshooting, `code-guard doctor` (or `code-guard doctor ---json`) validates the canonical bundled payload alongside the active runtime -and providers without exporting or updating it. Healthy diagnostics exit `0` -and completed unhealthy diagnostics exit `1`. Reports contain resolved paths -and environment details that may be sensitive when shared. - -Direct `--skill-path` use is intrinsically version-coupled to the installed -Python distribution. An export is a snapshot and contains a generated -`.agent-code-guard-version` marker with the producing distribution version. -After upgrading Agent Code Guard, callers must replace or re-export their -agent-installed snapshot. Code Guard performs no background or automatic agent -updates. +unit. It contains the `code-guard` CLI, runtime, and an inert, +version-matched skill payload. Keep their lifecycle steps distinct: + +1. Install the Python distribution with pipx, pip, or uv. +2. Invoke the installed `code-guard` CLI. +3. Locate the bundled skill: + + ```bash + code-guard --skill-path + ``` + +4. If the agent platform needs a copied payload, optionally export it: + + ```bash + code-guard --export-skill + ``` + +5. Let the agent platform discover or activate that directory through its own + supported mechanism. + +pipx installs and isolates the command; it does not register the skill with +every agent platform. Agent Code Guard does not know a universal skill +directory or activation API. Platform activation is separate, and exporting +into a persistent skill directory or changing platform configuration requires +user authorization. + +CLI-only use needs no skill export. For example, +`code-guard . --changed-only` runs independently of whether a platform has +activated the bundled skill. The skill does not affect startup, scope, +configuration, parser loading, findings, or exits. + +## Discovery and export guarantees + +`--skill-path` prints the absolute path of the active installed +distribution's canonical payload without project discovery, configuration +loading, Git work, or guard execution. + +`--export-skill` copies into exactly the supplied directory. The target must +be missing or empty; export rejects a non-empty target and never overwrites it. +The export contains `SKILL.md`, `LICENSE.txt`, `agents/openai.yaml`, the +policy files under `references/`, and a generated +`.agent-code-guard-version` marker recording the producing distribution +identity. After upgrading Agent Code Guard, refresh any exported snapshot so +the platform uses the newly installed version-matched skill. + +The checkout compatibility runner at +`skills/code-guard/scripts/code_guard.py` is for repository and skill +compatibility development. It is excluded from installed skill payloads and is +not a normal installation or execution path. + +For read-only troubleshooting, `code-guard doctor` or +`code-guard doctor --json` validates the bundled payload along with the active +runtime and providers. It does not export or activate a skill. See the +[human and agent workflow](agent-workflow.md) for execution cadence rather than +duplicating it here. diff --git a/docs/usage.md b/docs/usage.md index 8c5a805..e16537b 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -282,7 +282,18 @@ has no required policy work. ## Agent integration -CLI-only use needs no skill export. Installed distributions carry a -version-matched skill payload. Locate it with `code-guard --skill-path` or copy -it to an empty target with `code-guard --export-skill `. -See [Skill distribution](skill-distribution.md) for the complete contract. +After a meaningful editing turn in Git, the normal structured agent command is: + +```bash +code-guard . --changed-only --json --json-mode compact +``` + +Outside Git, pass the exact edited paths instead. An optional, user-authorized +platform hook may add `--ci`; this changes REVIEW's process exit from `1` to +`0` without hiding its findings or changing FAIL and tool-error exits. +Agent Code Guard does not install hooks. + +See the [human and agent workflow](agent-workflow.md) for the repeated manual +and hook-assisted loop. Installed distributions also carry a version-matched +skill payload; [skill distribution](skill-distribution.md) documents discovery, +export, and platform activation. diff --git a/skills/code-guard/SKILL.md b/skills/code-guard/SKILL.md index 2a77e7d..f79ec8e 100644 --- a/skills/code-guard/SKILL.md +++ b/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. From 2e69ff7e30f44a8d6e868a9870b2adb792f717da Mon Sep 17 00:00:00 2001 From: Stef Kariotidis Date: Thu, 27 Aug 2026 18:23:43 +0300 Subject: [PATCH 5/6] Fix packaged README reference links --- README.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 774c92d..4e3b2a6 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ code-guard doctor ``` `--version` confirms the installed distribution identity. `doctor` checks the -active installation's health. See the [usage guide](docs/usage.md) for virtual +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 @@ -91,7 +91,7 @@ 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](docs/agent-workflow.md) for repeated human and +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 @@ -113,7 +113,7 @@ 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](docs/agent-workflow.md) owns the complete manual and +[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 @@ -146,7 +146,7 @@ measurement. A REVIEW is not proof of a defect or a mandatory refactor. 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](docs/guard-admission.md). +[Guard admission](https://github.com/stef-k/agent-code-guard/blob/main/docs/guard-admission.md). ### Result and JSON reference @@ -155,7 +155,7 @@ 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](docs/usage.md) for the schema and +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 @@ -183,7 +183,7 @@ 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](docs/language-support.md). +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 @@ -195,13 +195,13 @@ code-guard --export-skill ``` Skill activation is platform-specific and is not performed by pipx or Code -Guard. See [Skill distribution](docs/skill-distribution.md). The checkout +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](docs/configuration.md). +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. @@ -212,24 +212,24 @@ 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](docs/platform-support.md) for supported binary platforms and +[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](docs/README.md) -- [Agent workflow](docs/agent-workflow.md) -- [Usage and CLI reference](docs/usage.md) -- [Configuration](docs/configuration.md) -- [Language support](docs/language-support.md) -- [Platform support](docs/platform-support.md) -- [Skill distribution](docs/skill-distribution.md) +- [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](SECURITY.md) for vulnerabilities. +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](LICENSE). +canonical implementation. Licensed under the [MIT License](https://github.com/stef-k/agent-code-guard/blob/main/LICENSE). From 7b48c653a0c76b715fae9fc2b2f37834ae36f1eb Mon Sep 17 00:00:00 2001 From: Stef Kariotidis Date: Thu, 27 Aug 2026 18:49:10 +0300 Subject: [PATCH 6/6] Clarify parser exits and agent authorization --- README.md | 11 +++++++---- docs/agent-workflow.md | 17 +++++++++++------ 2 files changed, 18 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 4e3b2a6..e52cfee 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,8 @@ Copy this prompt to a coding agent: > 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 or configuring hooks. +> 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. @@ -121,9 +122,11 @@ hook-assisted process. - **PASS** — no special action; exit `0`. - **REVIEW** — inspect and decide whether genuine structural improvement is warranted; normally exit `1`. -- **FAIL** — blocks normal completion until fixed or an explicitly authorized - exception applies; exit `2`. -- A tool, invocation, configuration, scope, or provider error exits `3`. +- **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. diff --git a/docs/agent-workflow.md b/docs/agent-workflow.md index bb56703..a76bea1 100644 --- a/docs/agent-workflow.md +++ b/docs/agent-workflow.md @@ -53,8 +53,10 @@ declaring completion. PASS means continue. REVIEW means inspect and either make a genuine improvement or retain the code with an honest justification; it is not automatically a defect. FAIL blocks normal completion until corrected or covered by an -explicitly authorized policy exception. Tool or invocation errors mean the -analysis did not complete. +explicitly authorized policy exception. An argparse usage or invalid-choice +error exits `2` with usage/error text on stderr and no completed report. Other +Code Guard tool, configuration, scope, or provider errors exit `3`; these errors +also mean the analysis did not complete. ## Manual agent loop @@ -69,9 +71,10 @@ Git supplies staged, unstaged, and untracked candidates within the positional bounds. The process exits are exact: - PASS: `0` -- REVIEW: `1` -- FAIL: `2` -- tool or invocation error: `3` +- REVIEW: `1`, or `0` with `--ci` +- completed FAIL: `2` +- argparse usage/invalid-choice error: `2`, stderr usage/error, no completed report +- other Code Guard tool/configuration/scope/provider error: `3` The agent inspects REVIEW and FAIL findings, applies judgment, loads only the named required policies, and reruns after relevant correction. @@ -96,7 +99,9 @@ code-guard . --changed-only --ci --json --json-mode compact ``` `--ci` changes only REVIEW's process exit from `1` to `0`. REVIEW findings -remain visible and require inspection; FAIL remains `2`, and tool or invocation +remain visible and require inspection. Completed FAIL remains `2`; argparse +usage or invalid-choice errors remain `2` with stderr usage/error and no +completed report; other Code Guard tool, configuration, scope, or provider errors remain `3`. Hook output must not be suppressed. Hook syntax and configuration paths are platform-specific. The agent must