AGENTS.md git:20260910.04d180dA

Immutable. This exact content is served forever at /api/v1/blob/7214c5411225bd0a.

# AGENTS.md

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

## Workspace identity

- The canonical upstream is `https://github.com/hermes-labs-ai/lintlang.git`.
- Treat `git worktree list` as the authority for active linked worktrees.
- Never assume the checked-out local branch matches public `origin/main`; verify the remote, branch, status, and intended base before editing.
- Maintainers: `WORKSPACE.md` in the git checkout records which local clone is
  canonical. It is not part of the published package and is not needed to work
  on the code.

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

## Key paths

- `src/lintlang/` — package source (detectors, CLI, preflight)
- `tests/` — pytest suite, including packaging-boundary and doc-consistency checks
- `samples/` — clean and deliberately bad fixtures used by CI and docs
- `action.yml` — the GitHub Action wrapper around the CLI

## 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/
python -m build
```

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

## Definition of done

- `pytest -q` and `ruff check src/ tests/` pass
- new or changed detector behavior has a covering test and a fixture in `samples/` if user-visible
- `lintlang scan samples/clean_config.yaml` still exits clean
- README, `AGENTS.md`, and CLI `--help` output stay consistent with the change
- no new performance, accuracy, or production-readiness claim was added without evidence