git:20260718.481cc8d to git:20260805.8c3764a

8 added, 0 removed. Audit A to A.

# AGENTS.md

`lintlang` is a static linter for AI agent configs, tool definitions, and system prompts.

+ ## Workspace identity

+ - Read `WORKSPACE.md` before choosing a checkout, branch, or handoff.

+ - The canonical upstream is `https://github.com/hermes-labs-ai/lintlang.git`.

+ - On the Hermes Labs maintainer workstation, the canonical development checkout is `/Users/rbr_lpci/github-projects/lintlang`.

+ - Treat `git worktree list` as the authority for active linked worktrees. Directories under `ai-infra`, `Documents/Codex`, and `Documents/HAL/_handoffs` are evidence or delivery artifacts unless a current task explicitly says otherwise.

+ - Never assume the checked-out local branch matches public `origin/main`; verify the remote, branch, status, and intended base before editing.

## 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, 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

- 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 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 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