AGENTS.md ยท diff
git:20260419.73bf39b to git:20260718.481cc8d
15 added, 6 removed. Audit A to A.
# AGENTS.md
`lintlang` is a static linter for AI agent configs, tool definitions, and system prompts.
## Use it for
- linting tool descriptions before agents start choosing the wrong tools
- checking prompts and configs for missing constraints, schema mismatches, and role confusion
- - running a zero-LLM CI gate over YAML, JSON, and prompt text
+ - running a zero-LLM CI gate over YAML, JSON, prompt text, and Python source files
+ - scanning `.py` files to find embedded prompts and uncalibrated thresholds (P1/P2 detectors)
+ - preflighting one present instruction plus explicit typed context before a host sends it
## Do not use it for
- runtime evaluation
- dynamic agent testing
- proving an agent is safe in production
+ - retrieving preferences from history, deciding truth, or silently rewriting/sending prompts
## Minimal commands
```bash
pip install -e ".[dev]"
lintlang --help
lintlang scan samples/bad_tool_descriptions.yaml
+ printf '%s' 'Is it true that X?' | lintlang preflight - --format json
pytest -q
ruff check src/ tests/
```
## Output shape
- - terminal verdicts: `PASS`, `REVIEW`, or `FAIL`
- - structural findings by pattern `H1` through `H7`
+ - repository scan outcomes: `ERROR`, `PASS`, `REVIEW`, or `FAIL`
+ - structural findings by pattern `H1` through `H7`, plus Python pipeline findings `P1` and `P2`
- JSON output for CI via `--format json`
+ - preflight states: `ALLOW`, `NOTICE`, `HOLD`, `UNAVAILABLE`, or `ERROR`
+ - preflight evidence uses exact code-point spans and stable `PF001`-`PF005` IDs
## Success means
- the same config file produces the same verdict and findings
- scan output points to concrete locations and rewrite guidance
- tests and sample self-scan pass offline
+ - unavailable preflight coverage is explicit and default output contains no raw prompt/context/patch text
## Common failure cases
- users expect lintlang to judge runtime model behavior
- - configs are syntactically valid but still too underspecified to be safe
- - teams gate only on syntax linters and miss language-level failure modes
+ - configs are syntactically valid but still underspecified for their intended use
+ - teams gate only on syntax and do not review language-level instruction risks
## Maintainer notes
- - keep detector language aligned with actual failure modes in the samples
+ - keep detector language aligned with the exact patterns exercised by the samples
- keep CLI examples and severity semantics aligned with README
- keep the tool fully offline and deterministic
+ - keep repository `scan` and in-flight `preflight` result types and exit semantics separate
+ - keep heuristic preflight findings notice-only; only exact contract/conflict rules may hold