@aurelienbbn/agentlint 0.1.0

package/dist/node-yh9mLvnE.mjs

@@ -0,0 +1,137 @@
+import { Schema } from "effect";
+//#region src/domain/flag.ts
+/**
+* Flag types — what rules produce when they detect patterns.
+*
+* {@link FlagOptions} is the rule-author API (passed to `context.flag()`).
+* {@link FlagRecord} is the enriched internal record used by the reporter.
+*
+* @module
+* @since 0.1.0
+*/
+/**
+* Enriched flag record after processing — ready for the reporter.
+*
+* Uses `Schema.Class` for structural equality AND runtime validation
+* on construction — invalid fields throw a clear `ParseError`.
+*
+* @since 0.1.0
+* @category models
+*/
+var FlagRecord = class extends Schema.Class("FlagRecord")({
+	ruleName: Schema.String,
+	filename: Schema.String,
+	line: Schema.Number,
+	col: Schema.Number,
+	message: Schema.String,
+	sourceSnippet: Schema.String,
+	hash: Schema.String,
+	instruction: Schema.UndefinedOr(Schema.String),
+	suggest: Schema.UndefinedOr(Schema.String)
+}) {};
+//#endregion
+//#region src/domain/node.ts
+/**
+* Lazy wrapper around tree-sitter's `Node`.
+*
+* Provides a stable public API that keeps the tree-sitter dependency
+* out of the consumer-facing surface. Children and parent are wrapped
+* on first access — nodes that are never inspected cost nothing.
+*
+* @module
+* @since 0.1.0
+*/
+/**
+* 0-indexed position in source text.
+*
+* Defined as a `Schema.Struct` so positions can be decoded and
+* validated from external sources if needed.
+*
+* @since 0.1.0
+* @category models
+*/
+const Position = Schema.Struct({
+	row: Schema.Number,
+	column: Schema.Number
+});
+/**
+* Private implementation of {@link AgentReviewNode}.
+*
+* Wraps a tree-sitter `Node` and lazily creates child/parent wrappers
+* on first access. Nodes that are never traversed incur zero allocation.
+*
+* @since 0.1.0
+* @category internals
+*/
+var AgentReviewNodeImpl = class AgentReviewNodeImpl {
+	#inner;
+	#children;
+	#parent;
+	constructor(inner) {
+		this.#inner = inner;
+	}
+	get type() {
+		return this.#inner.type;
+	}
+	get text() {
+		return this.#inner.text;
+	}
+	get startPosition() {
+		return this.#inner.startPosition;
+	}
+	get endPosition() {
+		return this.#inner.endPosition;
+	}
+	get isNamed() {
+		return this.#inner.isNamed;
+	}
+	get childCount() {
+		return this.#inner.childCount;
+	}
+	get children() {
+		if (this.#children === void 0) {
+			const result = [];
+			for (const c of this.#inner.children) if (c !== null) result.push(new AgentReviewNodeImpl(c));
+			this.#children = result;
+		}
+		return this.#children;
+	}
+	get parent() {
+		if (this.#parent === void 0) {
+			const p = this.#inner.parent;
+			this.#parent = p ? new AgentReviewNodeImpl(p) : null;
+		}
+		return this.#parent;
+	}
+	childByFieldName(name) {
+		const child = this.#inner.childForFieldName(name);
+		return child ? new AgentReviewNodeImpl(child) : null;
+	}
+	childrenByType(type) {
+		const result = [];
+		for (const c of this.#inner.children) if (c !== null && c.type === type) result.push(new AgentReviewNodeImpl(c));
+		return result;
+	}
+	descendantsOfType(type) {
+		const result = [];
+		for (const c of this.#inner.descendantsOfType(type)) if (c !== null) result.push(new AgentReviewNodeImpl(c));
+		return result;
+	}
+};
+/**
+* Wrap a raw tree-sitter node in the public {@link AgentReviewNode} interface.
+*
+* This is the only bridge between the internal tree-sitter dependency
+* and the consumer-facing API. All child/parent nodes are lazily wrapped
+* on access.
+*
+* @since 0.1.0
+* @category constructors
+*/
+function wrapNode(inner) {
+	return new AgentReviewNodeImpl(inner);
+}
+//#endregion
+export { wrapNode as n, FlagRecord as r, Position as t };
+
+//# sourceMappingURL=node-yh9mLvnE.mjs.map

package/dist/node-yh9mLvnE.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-yh9mLvnE.mjs","names":["#inner","#children","#parent"],"sources":["../src/domain/flag.ts","../src/domain/node.ts"],"sourcesContent":["/**\n * Flag types — what rules produce when they detect patterns.\n *\n * {@link FlagOptions} is the rule-author API (passed to `context.flag()`).\n * {@link FlagRecord} is the enriched internal record used by the reporter.\n *\n * @module\n * @since 0.1.0\n */\n\nimport { Schema } from \"effect\";\nimport type { AgentReviewNode } from \"./node.js\";\n\n/**\n * Options passed to `context.flag()` by rule visitors.\n *\n * @since 0.1.0\n * @category models\n */\nexport interface FlagOptions {\n  /** The AST node that triggered the match. */\n  readonly node: AgentReviewNode;\n  /** Short one-liner displayed next to file:line in output. */\n  readonly message: string;\n  /**\n   * Override `meta.instruction` for this specific match.\n   * Appears inline in per-match notes.\n   */\n  readonly instruction?: string | undefined;\n  /** Hint toward the fix. Not a command - just a nudge. */\n  readonly suggest?: string | undefined;\n}\n\n/**\n * Enriched flag record after processing — ready for the reporter.\n *\n * Uses `Schema.Class` for structural equality AND runtime validation\n * on construction — invalid fields throw a clear `ParseError`.\n *\n * @since 0.1.0\n * @category models\n */\nexport class FlagRecord extends Schema.Class<FlagRecord>(\"FlagRecord\")({\n  ruleName: Schema.String,\n  filename: Schema.String,\n  /** 1-based line number. */\n  line: Schema.Number,\n  /** 1-based column number. */\n  col: Schema.Number,\n  message: Schema.String,\n  sourceSnippet: Schema.String,\n  /** 7-char hex hash for stable match identification. */\n  hash: Schema.String,\n  instruction: Schema.UndefinedOr(Schema.String),\n  suggest: Schema.UndefinedOr(Schema.String),\n}) {}\n","/**\n * Lazy wrapper around tree-sitter's `Node`.\n *\n * Provides a stable public API that keeps the tree-sitter dependency\n * out of the consumer-facing surface. Children and parent are wrapped\n * on first access — nodes that are never inspected cost nothing.\n *\n * @module\n * @since 0.1.0\n */\n\nimport { Schema } from \"effect\";\nimport type { Node as TSNode } from \"web-tree-sitter\";\n\n/**\n * 0-indexed position in source text.\n *\n * Defined as a `Schema.Struct` so positions can be decoded and\n * validated from external sources if needed.\n *\n * @since 0.1.0\n * @category models\n */\nexport const Position = Schema.Struct({\n  row: Schema.Number,\n  column: Schema.Number,\n});\n\n/** @since 0.1.0 */\nexport type Position = Schema.Schema.Type<typeof Position>;\n\n/**\n * Read-only view of a syntax tree node.\n *\n * One universal type — no per-kind subtypes. Rules narrow via\n * `node.type` string checks and field accessors.\n *\n * @since 0.1.0\n * @category models\n */\nexport interface AgentReviewNode {\n  /** tree-sitter grammar node type (e.g. `\"function_declaration\"`, `\"comment\"`) */\n  readonly type: string;\n  /** Full source text covered by this node. */\n  readonly text: string;\n  /** 0-indexed start position. */\n  readonly startPosition: Position;\n  /** 0-indexed end position. */\n  readonly endPosition: Position;\n  /** Whether this is a named node in the grammar. */\n  readonly isNamed: boolean;\n  /** Direct child nodes (lazily wrapped). */\n  readonly children: ReadonlyArray<AgentReviewNode>;\n  /** Parent node, or null for the root. */\n  readonly parent: AgentReviewNode | null;\n  /** Number of direct children. */\n  readonly childCount: number;\n\n  /** Get a child by its grammar field name (e.g. `\"name\"`, `\"body\"`). */\n  childByFieldName(name: string): AgentReviewNode | null;\n  /** All direct children matching the given node type. */\n  childrenByType(type: string): ReadonlyArray<AgentReviewNode>;\n  /** Recursively collect all descendants matching the given node type. */\n  descendantsOfType(type: string): ReadonlyArray<AgentReviewNode>;\n}\n\n/**\n * Private implementation of {@link AgentReviewNode}.\n *\n * Wraps a tree-sitter `Node` and lazily creates child/parent wrappers\n * on first access. Nodes that are never traversed incur zero allocation.\n *\n * @since 0.1.0\n * @category internals\n */\nclass AgentReviewNodeImpl implements AgentReviewNode {\n  readonly #inner: TSNode;\n  #children: ReadonlyArray<AgentReviewNode> | undefined;\n  #parent: AgentReviewNode | null | undefined;\n\n  constructor(inner: TSNode) {\n    this.#inner = inner;\n  }\n\n  get type(): string {\n    return this.#inner.type;\n  }\n\n  get text(): string {\n    return this.#inner.text;\n  }\n\n  get startPosition(): Position {\n    return this.#inner.startPosition;\n  }\n\n  get endPosition(): Position {\n    return this.#inner.endPosition;\n  }\n\n  get isNamed(): boolean {\n    return this.#inner.isNamed;\n  }\n\n  get childCount(): number {\n    return this.#inner.childCount;\n  }\n\n  get children(): ReadonlyArray<AgentReviewNode> {\n    if (this.#children === undefined) {\n      const result: AgentReviewNode[] = [];\n      for (const c of this.#inner.children) {\n        if (c !== null) result.push(new AgentReviewNodeImpl(c));\n      }\n      this.#children = result;\n    }\n    return this.#children;\n  }\n\n  get parent(): AgentReviewNode | null {\n    if (this.#parent === undefined) {\n      const p = this.#inner.parent;\n      this.#parent = p ? new AgentReviewNodeImpl(p) : null;\n    }\n    return this.#parent;\n  }\n\n  childByFieldName(name: string): AgentReviewNode | null {\n    const child = this.#inner.childForFieldName(name);\n    return child ? new AgentReviewNodeImpl(child) : null;\n  }\n\n  childrenByType(type: string): ReadonlyArray<AgentReviewNode> {\n    const result: AgentReviewNode[] = [];\n    for (const c of this.#inner.children) {\n      if (c !== null && c.type === type) result.push(new AgentReviewNodeImpl(c));\n    }\n    return result;\n  }\n\n  descendantsOfType(type: string): ReadonlyArray<AgentReviewNode> {\n    const result: AgentReviewNode[] = [];\n    for (const c of this.#inner.descendantsOfType(type)) {\n      if (c !== null) result.push(new AgentReviewNodeImpl(c));\n    }\n    return result;\n  }\n}\n\n/**\n * Wrap a raw tree-sitter node in the public {@link AgentReviewNode} interface.\n *\n * This is the only bridge between the internal tree-sitter dependency\n * and the consumer-facing API. All child/parent nodes are lazily wrapped\n * on access.\n *\n * @since 0.1.0\n * @category constructors\n */\nexport function wrapNode(inner: TSNode): AgentReviewNode {\n  return new AgentReviewNodeImpl(inner);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA0CA,IAAa,aAAb,cAAgC,OAAO,MAAkB,aAAa,CAAC;CACrE,UAAU,OAAO;CACjB,UAAU,OAAO;CAEjB,MAAM,OAAO;CAEb,KAAK,OAAO;CACZ,SAAS,OAAO;CAChB,eAAe,OAAO;CAEtB,MAAM,OAAO;CACb,aAAa,OAAO,YAAY,OAAO,OAAO;CAC9C,SAAS,OAAO,YAAY,OAAO,OAAO;CAC3C,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;AChCH,MAAa,WAAW,OAAO,OAAO;CACpC,KAAK,OAAO;CACZ,QAAQ,OAAO;CAChB,CAAC;;;;;;;;;;AAiDF,IAAM,sBAAN,MAAM,oBAA+C;CACnD;CACA;CACA;CAEA,YAAY,OAAe;AACzB,QAAA,QAAc;;CAGhB,IAAI,OAAe;AACjB,SAAO,MAAA,MAAY;;CAGrB,IAAI,OAAe;AACjB,SAAO,MAAA,MAAY;;CAGrB,IAAI,gBAA0B;AAC5B,SAAO,MAAA,MAAY;;CAGrB,IAAI,cAAwB;AAC1B,SAAO,MAAA,MAAY;;CAGrB,IAAI,UAAmB;AACrB,SAAO,MAAA,MAAY;;CAGrB,IAAI,aAAqB;AACvB,SAAO,MAAA,MAAY;;CAGrB,IAAI,WAA2C;AAC7C,MAAI,MAAA,aAAmB,KAAA,GAAW;GAChC,MAAM,SAA4B,EAAE;AACpC,QAAK,MAAM,KAAK,MAAA,MAAY,SAC1B,KAAI,MAAM,KAAM,QAAO,KAAK,IAAI,oBAAoB,EAAE,CAAC;AAEzD,SAAA,WAAiB;;AAEnB,SAAO,MAAA;;CAGT,IAAI,SAAiC;AACnC,MAAI,MAAA,WAAiB,KAAA,GAAW;GAC9B,MAAM,IAAI,MAAA,MAAY;AACtB,SAAA,SAAe,IAAI,IAAI,oBAAoB,EAAE,GAAG;;AAElD,SAAO,MAAA;;CAGT,iBAAiB,MAAsC;EACrD,MAAM,QAAQ,MAAA,MAAY,kBAAkB,KAAK;AACjD,SAAO,QAAQ,IAAI,oBAAoB,MAAM,GAAG;;CAGlD,eAAe,MAA8C;EAC3D,MAAM,SAA4B,EAAE;AACpC,OAAK,MAAM,KAAK,MAAA,MAAY,SAC1B,KAAI,MAAM,QAAQ,EAAE,SAAS,KAAM,QAAO,KAAK,IAAI,oBAAoB,EAAE,CAAC;AAE5E,SAAO;;CAGT,kBAAkB,MAA8C;EAC9D,MAAM,SAA4B,EAAE;AACpC,OAAK,MAAM,KAAK,MAAA,MAAY,kBAAkB,KAAK,CACjD,KAAI,MAAM,KAAM,QAAO,KAAK,IAAI,oBAAoB,EAAE,CAAC;AAEzD,SAAO;;;;;;;;;;;;;AAcX,SAAgB,SAAS,OAAgC;AACvD,QAAO,IAAI,oBAAoB,MAAM"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@aurelienbbn/agentlint",
+  "version": "0.1.0",
+  "description": "Stateless, deterministic CLI that bridges traditional linters and AI-assisted code review",
+  "keywords": [
+    "agent",
+    "ai",
+    "ast",
+    "code-review",
+    "linter",
+    "tanstack-intent",
+    "tree-sitter"
+  ],
+  "license": "MIT",
+  "author": "Aurelien Bobenrieth",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aurelienbobenrieth/agentlint"
+  },
+  "bin": {
+    "agentlint": "dist/bin.mjs"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "!skills/_artifacts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "@effect/platform-node": "4.0.0-beta.43",
+    "effect": "^4.0.0-beta.43",
+    "jiti": "^2.4.2",
+    "picomatch": "^4.0.2",
+    "web-tree-sitter": "^0.25.3"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.6.0",
+    "@changesets/cli": "^2.30.0",
+    "@tanstack/intent": "latest",
+    "@types/node": "^22.13.14",
+    "@types/picomatch": "^4.0.0",
+    "oxfmt": "latest",
+    "oxlint": "^0.16.7",
+    "tree-sitter-wasms": "^0.1.13",
+    "tsdown": "latest",
+    "typescript": "^5.7.3",
+    "vitest": "^3.1.1"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "oxlint",
+    "fmt": "oxfmt --write",
+    "fmt:check": "oxfmt --check",
+    "changeset": "changeset",
+    "check": "pnpm typecheck && pnpm lint && pnpm fmt:check && pnpm test"
+  }
+}

package/skills/agentlint/rule-advisor/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: agentlint/rule-advisor
+description: >
+  Classify a code quality concern into the right enforcement tool and act on it.
+  Activate when the user wants to enforce a pattern, catch a mistake, add a
+  check, create a rule, prevent a practice, guard against regressions, set up
+  linting, improve their feedback loop, or asks "how do I make sure X."
+type: core
+library: agentlint
+library_version: "0.1.0"
+sources:
+  - "aurelienbobenrieth/agentlint:README.md"
+  - "aurelienbobenrieth/agentlint:CONTRIBUTING.md"
+---
+
+# Rule Advisor
+
+Classify what the user wants to enforce, pick the right tool, act on it.
+
+## How to use this skill
+
+1. Read the user's intent
+2. If the intent is too vague to classify, clarify with one targeted question
+3. Once clear, classify using the decision tree below
+4. State your classification and reasoning in one sentence
+5. Implement or guide the user to implement it
+
+## Decision tree
+
+**Can a pattern be detected by looking at code structure (AST, file, imports)?**
+
+NO, and no metric or structure can trigger detection either
+→ Document as a code review guideline. This is a team convention.
+
+YES, and the correct action is always the same (mechanical fix)
+→ Existing linter rule (e.g. oxlint, eslint, biome, or similar)
+if a well-known rule exists for it.
+→ Custom lint rule (e.g. eslint plugin, or similar)
+if it's project-specific but still deterministic.
+→ Codemod (e.g. jscodeshift, ts-morph, or similar)
+if it needs automated rewriting across files.
+
+YES, but what to do about each finding requires judgment
+→ **agentlint rule.** Deterministic detection, AI-evaluated action.
+
+**Is it about module or dependency structure?**
+→ Dependency analysis (e.g. dependency-cruiser, madge, or similar)
+for import direction and boundaries.
+→ CI check or agentlint rule for file/directory naming conventions.
+
+**Is it about runtime behavior?**
+→ Type-level enforcement (e.g. branded types, schema validation, or similar)
+if it can be caught at compile time.
+→ Tests (unit, integration, property-based) if it needs execution.
+→ Monitoring if it needs production signals.
+
+## When the answer is agentlint
+
+agentlint's niche: deterministic detection + non-deterministic evaluation.
+
+Three scopes are available:
+
+- **Single-node visitor** - flag individual AST nodes (comments, functions,
+  catch blocks, magic numbers)
+- **Program visitor** - analyze the full file AST (duplicate function bodies,
+  nested loops, export counts, prop counts)
+- **File-level targeting** - use include/ignore globs to scope rules to
+  specific directories or file patterns
+
+### Rule template
+
+```typescript
+import { defineRule } from "agentlint";
+
+const myRule = defineRule({
+  meta: {
+    name: "rule-name",
+    description: "One-line description of what this detects",
+    languages: ["ts", "tsx"],
+    include: ["src/**"], // optional: scope to paths
+    ignore: ["**/*.test.*"], // optional: exclude paths
+    instruction: `[Be specific. Tell the AI agent exactly what to evaluate
+for each finding, when a finding is acceptable, and what action to take
+when it is a true positive.]`,
+  },
+  createOnce(context) {
+    return {
+      // Available visitors: program, function_declaration, arrow_function,
+      // call_expression, identifier, string, comment, class_declaration,
+      // method_definition, property_identifier, type_annotation,
+      // interface_declaration, import_statement, export_statement,
+      // variable_declarator, if_statement, return_statement,
+      // object, array, pair, jsx_element, jsx_self_closing_element
+      comment(node) {
+        context.flag({ node, message: node.text.trim() });
+      },
+    };
+  },
+});
+```
+
+### AgentReviewNode API
+
+- `text` - source text of the node
+- `type` - tree-sitter node type
+- `startPosition` / `endPosition` - `{ row, column }`
+- `children` - child nodes array
+- `parent` - parent node or undefined
+- `child(i)` / `namedChild(i)` - get child by index
+- `childForFieldName(name)` - get child by field name
+- `descendantsOfType(type)` - find all descendants matching a type
+
+### Writing good instructions
+
+The instruction is what the AI agent reads to evaluate each finding.
+It determines whether findings are actionable or noise.
+
+Bad: "Review this code"
+
+Good: "Evaluate each flagged catch block. If the error is logged and
+re-thrown, it is acceptable. If the error is silently swallowed - empty
+catch or catch with only a console.log - suggest adding proper error
+handling or propagation."
+
+### Testing
+
+```bash
+npx agentlint check --all --rule rule-name
+npx agentlint check src/handlers/checkout.ts --rule rule-name
+npx agentlint check --all --rule rule-name --dry-run
+```

package/skills/agentlint/usage/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: agentlint/usage
+description: >
+  Run agentlint CLI after code changes to catch patterns for AI evaluation.
+  Activate when finishing code modifications, before committing, or when
+  the developer asks to lint, scan, or review code with agentlint. Covers
+  agentlint check, agentlint list, agentlint review, agentlint init,
+  inline suppression, and output interpretation.
+type: core
+library: agentlint
+library_version: "0.1.0"
+sources:
+  - "aurelienbobenrieth/agentlint:README.md"
+  - "aurelienbobenrieth/agentlint:src/bin.ts"
+---
+
+# agentlint
+
+Stateless, deterministic linter whose output is designed for you (an AI coding agent) to evaluate. It uses tree-sitter to parse code, runs visitor-based rules that flag suspicious patterns, and outputs structured reports with natural language instructions.
+
+## Setup
+
+```bash
+npm install agentlint
+npx agentlint init
+```
+
+This creates `agentlint.config.ts` with a starter template. Add rules to the `rules` object.
+
+## Core Patterns
+
+### Run after code changes
+
+```bash
+# Default: scan files changed in current branch
+npx agentlint check
+
+# Scan specific files or globs
+npx agentlint check src/utils.ts "src/**/*.tsx"
+
+# Scan all files
+npx agentlint check --all
+
+# Only run a specific rule
+npx agentlint check --rule no-noise-comments
+
+# Dry-run (counts only, no instruction blocks)
+npx agentlint check --dry-run
+
+# Diff against a specific branch
+npx agentlint check --base main
+```
+
+### Read and act on output
+
+Output is grouped by rule. Each rule section contains:
+
+1. **Match listings** with `[hash] file:line:col  source-line`
+2. **Instruction block** explaining how to evaluate the matches
+
+Process one rule section at a time:
+
+1. Read the instruction block for the rule
+2. Evaluate each match against the criteria in the instruction
+3. For matches that are genuine issues: fix them
+4. For matches that are acceptable: move on
+5. Re-run `agentlint check` after fixes — resolved matches disappear
+
+### Mark findings as reviewed
+
+```bash
+# Mark specific hashes as reviewed (they disappear from future output)
+npx agentlint review abc1234 def5678
+
+# Mark all current flags as reviewed
+npx agentlint review --all
+
+# Reset reviewed state (see all flags again)
+npx agentlint review --reset
+```
+
+### Suppress inline
+
+```typescript
+// agentlint-ignore no-noise-comments -- explains the retry formula
+const delay = baseDelay * Math.pow(2, attempt);
+```
+
+### Write a rule
+
+```typescript
+import { defineConfig, defineRule } from "agentlint";
+
+const noTodos = defineRule({
+  meta: {
+    name: "no-todos",
+    description: "Flags TODO comments for evaluation",
+    languages: ["ts", "tsx"],
+    instruction: "Evaluate each TODO. Convert actionable ones to issues, remove stale ones.",
+  },
+  createOnce(context) {
+    return {
+      comment(node) {
+        if (node.text.includes("TODO")) {
+          context.flag({ node, message: node.text.trim() });
+        }
+      },
+    };
+  },
+});
+
+export default defineConfig({
+  include: ["src/**/*.{ts,tsx}"],
+  rules: { "no-todos": noTodos },
+});
+```
+
+## Common Mistakes
+
+### HIGH Exit code 1 is not an error
+
+Wrong:
+
+```bash
+# Treating non-zero exit as a failure and stopping
+npx agentlint check || echo "agentlint failed"
+```
+
+Correct:
+
+```bash
+# Exit code 1 means findings exist — read and evaluate the output
+npx agentlint check
+# Then process the stdout, don't treat it as a crash
+```
+
+agentlint exits with code 1 when findings exist. This is expected behavior, not a crash. Read the output and evaluate each finding.
+
+### HIGH Fixing all findings without reading instructions
+
+Wrong: Blindly "fixing" every flagged line without reading the rule's instruction block.
+
+Correct: Read the instruction block first. It tells you the evaluation criteria. Some findings are intentionally acceptable — the instruction explains which.
+
+### MEDIUM Looping on already-evaluated findings
+
+Wrong: Re-evaluating the same findings across multiple agentlint runs in one session.
+
+Correct: Evaluate each finding once. If it persists after your fix, tell the developer rather than retrying. Use `agentlint review <hash>` to mark evaluated findings.
+
+## Constraints
+
+- Process one rule section at a time, not all findings at once
+- Never attempt more than one fix per finding
+- If agentlint still flags something after your fix, tell the developer
+- When the instruction says "ask the developer," do that instead of guessing
+- Do not loop on findings you already evaluated in this session