Prepare Agent Code Guard 0.2.0

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.

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.

docs/agent-workflow.md

@@ -0,0 +1,117 @@
+# 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. 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
+
+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`, 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.
+
+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. 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
+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.

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 <target-directory>` 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 <target-directory>
+   ```
+
+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.

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 <target-directory>`.
-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.

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"

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.