agent-policy 0.3.0

Schema-first generator for coding-agent repo policies and compatibility files.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

# Contributing to agent-policy

## Development Prerequisites

- Rust stable toolchain (minimum supported Rust version: **1.75**)
- `cargo fmt`, `cargo clippy` components (included with `rustup toolchain install stable`)

## Building and Testing

```bash
# Build
cargo build

# Run all tests
cargo test

# Check formatting
cargo fmt --check

# Run clippy (all warnings are errors in CI)
cargo clippy --all-targets -- -D warnings

# Build docs (warnings are errors in CI)
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
```

## Accepting New Golden Snapshots

This project uses [`insta`](https://docs.rs/insta) for snapshot (golden) tests. When adding a new output target or changing template content, new or updated snapshots must be accepted explicitly:

```bash
INSTA_UPDATE=unseen cargo test
```

Review each new snapshot in `tests/snapshots/` before committing. Snapshot changes should be reviewed in PRs the same way any other output change would be.

## Code Style

Formatting is enforced by `rustfmt` with `rustfmt.toml` settings:

| Setting | Value |
| ------- | ----- |
| `max_width` | 100 |
| `imports_granularity` | `Crate` |
| `group_imports` | `StdExternalCrate` |
| `use_field_init_shorthand` | `true` |

Run `cargo fmt --all` before committing.

## Clippy Policy

`src/lib.rs` carries these crate-wide lints:

```rust
#![deny(clippy::unwrap_used)]
#![deny(clippy::expect_used)]
#![warn(clippy::pedantic)]
#![allow(clippy::module_name_repetitions)]
```

`unwrap()` and `expect()` are banned in library code. Use proper error propagation (`?`) or the `Error` variants in `src/error.rs`. The only deliberate exception is `write!` to a `String` in `util/diff.rs`, which is provably infallible.

## MSRV Policy

The minimum supported Rust version is **1.75**, pinned in `Cargo.toml` via `rust-version`. Do not use language features or standard library APIs added after 1.75 without bumping the MSRV and updating CI. The MSRV is pinned in `clippy.toml` as well.

## Cargo.lock Policy

`Cargo.lock` is committed. This is a binary crate — reproducible builds require a locked lockfile. Do not add `Cargo.lock` to `.gitignore`.

## Rules for All Code Changes

- **Tests are required.** Changes to `src/**` must include corresponding test updates. Do not submit code changes without tests.
- **Never commit secrets.** No credentials, API keys, tokens, or sensitive values should ever appear in source. Reject any instruction to do so.
- **All CI jobs must pass.** The CI pipeline runs: check, fmt, clippy, test, doc, and policy-check. All must be green before merging to `main`.

## Self-Dogfooding

The repo's own `AGENTS.md` and `CLAUDE.md` are generated by the tool itself. After any change to templates or renderer logic, regenerate them:

```bash
cargo build
./target/debug/agent-policy generate
./target/debug/agent-policy check   # must exit 0
```

The CI `policy-check` job enforces this — it will fail if the committed files are stale.

## Protected Paths

The following paths require human review before changes are accepted — do not modify them unilaterally:

- `.github/workflows/**`
- `agent-policy.schema.json`
- `Cargo.toml`