Context Linting

A lint gate for agent context: one rule line binds a file pattern to a registered checker, and the same line is what the agent reads when it opens the file.

ACDSL (Agentic Context Domain Specific Linter) is a wrapper around deterministic checkers. A rule names the files it governs and the program that checks them; acdsl check runs the program, the Read hook delivers the rule's text to the agent, and a verdict log counts how often each rule went red while its text was in context. That log decides which prose stays and which rule becomes gate-only. The language itself is a dozen fields on one line. The full paper, with the experiments behind the design, is acdsl-spec.pdf.

A rule

One line per rule in acdsl/rules.acdsl (task contracts live in their plan directories). The marker is the file class's comment prefix plus acdsl:; a .md or .html file closes it with -->.

//acdsl:ACDSL-GOLANG-FMT-001 gofmt anchor="\.go$" anchor-not="(/testdata/|^vendor/)" why="Every Go file is gofmt-formatted — run gofmt -w before committing"

The registry and the verifier contract

acdsl/registry.json maps a name to an invocation; a target repo overlays any name through acdsl/registry.local.json without touching the rules. argv must be non-empty, timeout_s within 1..300.

"gofmt": {
  "argv": ["go", "run", "./cmd/acdsl/verifiers/gofmtwrap"],
  "timeout_s": 30,
  "description": "fails when an anchored file is not gofmt-formatted"
}

Any executable that honors the contract can stand behind a name. The engine calls <argv...> <files-list-path> [key=value ...] under the entry's timeout; baseline verifiers shell out only through internal/shell.Run to allowlisted programs.

Check

acdsl check builds the git file universe once (git ls-files --cached --others --exclude-standard, so untracked files the agent just wrote are seen), resolves every anchor, runs each verifier, prints one line per violation (message: [RULE-ID] verifier — why, or JSON with -json) and appends a verdict record. It also refuses staged projection blocks and blocks committed at HEAD.

Fixtures. Every rule carries pass and fail sets under acdsl/testdata/<rule-id>/; acdsl fixtures proves the verifier against them. A rule without a failing fixture is unproven, and eviction needs green fixtures.

What the agent sees

In a Claude session the acdslhook PostToolUse(Read) hook injects the governing rules beside the Read result, as - [ID] why lines under ACDSL rules governing <path>:, on every read. The file on disk is never touched. It acts only when the session cwd holds acdsl/registry.json; park its hook group on the Hooks tab or type #disable inject:acdsl to switch it off.

For consumers that read bytes, acdsl project -file <path> writes the same lines into the file as a comment block in the file class's own syntax (never into JSON, .cue, .js, .bru, .acdsl or binaries). Blocks are working-copy only: make audit, the routine runner and the pre-commit hook strip or refuse them, and acdsl check refuses a committed one. Rules whose own consumers would break on a block carry projected="false" (ACDSL-SMINE-001, ACDSL-GOLANG-DOCS-001, ACDSL-SMINE-004 to -010).

acdsl project -plan <path> answers which rules would govern a path that does not exist yet; design plans record their planned files' rules through it.

The ablation loop

Every check run appends one JSONL record to $ACDSL_VERDICTS_PATH, else ~/.claude/acdsl/verdicts.jsonl (home-anchored, since worktrees die with their sessions). Zero-violation rows are the denominator; the branch is the session proxy. Logging is best-effort and never changes the exit code; ACDSL_VERDICTS_ENABLED=0 disables it.

{"ts": "2026-08-07T12:00:00Z", "root": "/abs/worktree", "branch": "claude/slug", "outcome": "clean",
 "rules": [{"id": "ACDSL-GOLANG-EXEC-001", "projected": true, "violations": 0}],
 "diagnostics": [{"id": "ACDSL-GOLANG-EXEC-001", "message": "file.go:12: ..."}]}

Statistics are keyed on (rule, projected): a rule flipped mid-window shows two rows, and that pair is the A/B comparison. check and fixtures never read the flag; enforcement is the constant, delivery the variable, and the prompt side carries no "also enforced" hint that would contaminate the arm.

acdsl verdicts -since 720h

The bar is a calibration, not a constant; the rule set churns, so the arms are never stationary. What the loop reliably gives is visibility: a heavily violated rule is unmissable. The end state is context that shrinks toward judgment rules and facts while everything mechanical lives as a gate.

How a rule gets made

The nightly smine-acdsl stage mines rules sessions keep breaking into change tasks; /fimplement lands each as one commit. Every task declares its route, in priority order; the lower routes are last resorts.

1. Established-tool config

   The check fits a tool the repo already gates with (golangci-lint via .golangci.yml, shellcheck, a JSON schema): a config edit, plus a rules.acdsl line on the existing wrapper verifier when the rule is new. The tool's config is the configuration surface, never a custom reimplementation.

2. Existing registry verifier

   A registered verifier covers it with other params or anchors: one rules.acdsl line (next free ID in its family) plus fixtures. No new code.

3. Generated verifier

   Only when the task says why routes 1 and 2 fail: the run generates the verifier, the registry entry, the rule and the fixtures, then proves them (acdsl fixtures, check -rule <id>, make audit). Bounds in acdsl/evalgen.json, enforced by ACDSL-GOLANG-GEN-001: Go only, a line cap, imports from the stdlib, this module or go.mod's require set (generation never adds a dependency), an exec allowlist, a timeout cap, bands F and A only, and autoApply: false so a nightly run never generates one unattended.

golangci-lint beside it

The seam is the tag doctrine of context/rules/go.md: a rule is [lint] with a Covered by <linter> bullet, or [prose]; a partly automatable rule is split in two. The gate ACDSL-GOLANG-DOCS-001 (linttags) reads .golangci.yml as text and goes red when a Covered by claim names a linter the config does not enable, so the config needs an explicit enable list. Where golangci-lint stands behind an ACDSL rule (ACDSL-GOLANG-LINT-001, registry entry golangci), the wrapper groups files by directory, reads JSON from a file, lifts the issue caps, drops (typecheck) findings and keeps findings on anchored files. Several linters fight the house style and stay off: ST1003 and revive's initialism check, ST1005, fieldalignment, gochecknoinits, gocritic/elseif.

Modes

acdsl/policy.json says who may change the rule system. acdsl check enforces it (compiled into bin/acdsl) by diffing the working tree against merge-base(HEAD, base), the base found from origin/HEAD → origin/main → main → master; the tool-policy gate refuses the writes at once. An agent branch cannot self-escalate; an unresolvable base in strict or gated mode is a hard error.

Task contracts stay usable in every mode while allow_task_contracts is true. New verifier binaries never depend on the mode: they go through the evalgen flow. For client-level strictness a target can also deny Edit(acdsl/**), Write(acdsl/**), Edit(**/*.acdsl) and Write(**/*.acdsl) in its .claude/settings.json.

Reach and distribution

acdsl dist -target <name> -dest <dir> ships a target's slice: the reach-covered rules as verbatim lines under a synced-from-smine header, the registry subset they name with argv rewritten to bin/verifiers/<name>, the prebuilt binaries and policy.json (mode from the source's dist_mode). The Context page's sync calls it in process when "sync acdsl" is on. A rule ships only when the target has files its anchor matches; skipped rules are reported and picked up by a later sync. Targets own their own *.acdsl files and registry.local.json; in a strict or gated target only entries listed in the policy's local_overrides are accepted. The deployed read hook activates by itself and logs to the shared home verdict sink.

The Context tab

The config server's Context tab shows the rule cards with their delivery badge and per-arm red rates, the eviction and re-projection candidates, the coverage derived from why citations, a run-fixtures button and the recent gate runs. reach is editable there; delivery is not. Scopes are the shared taxonomy of context/aspects.json: a rule's scope is its ID's second segment, an unregistered one shows amber, and a member cited by any rule cannot be deleted.

Commands

Source cmd/acdsl/main.go. Exit codes: 0 clean, 1 violations, 2 tool error. Environment: ACDSL_VERDICTS_PATH, ACDSL_VERDICTS_ENABLED=0.