@jqntn/agentdoctor 0.1.0

package/docs/api.md

@@ -0,0 +1,100 @@
+# Programmatic API
+
+agentdoctor is an ES module with no dependencies, so embedding it is one import.
+
+```js
+import { run } from '@jqntn/agentdoctor';
+
+const result = run('/path/to/repo', { includeUserScope: false });
+
+for (const finding of result.findings) {
+  console.log(finding.severity, finding.ruleId, `${finding.display}:${finding.line}`);
+}
+process.exitCode = result.findings.some((f) => f.severity === 'error') ? 1 : 0;
+```
+
+## `run(root, options?)`
+
+The one-call entry point: discovers config, loads any team policy, runs every rule.
+
+| Option | Type | Default | Effect |
+|---|---|---|---|
+| `includeUserScope` | boolean | `true` | Also scan `~/.claude` |
+| `home` | string | `os.homedir()` | Override the home directory (useful in tests) |
+| `policyPath` | string | auto-detect | Explicit policy file path |
+| `only` | string[] | all | Restrict to categories or rule ids |
+| `disabled` | string[] | none | Skip rules or categories |
+| `minSeverity` | `'error'\|'warning'\|'info'` | `'info'` | Severity floor |
+| `baseline` | `Set<string>` | empty | Fingerprints to suppress |
+
+Returns `{ findings, ran, suppressed, workspace, elapsedMs, version }`.
+
+### Finding shape
+
+```ts
+{
+  ruleId: string;        // e.g. "security/unrestricted-bash"
+  severity: 'error' | 'warning' | 'info';
+  category: 'correctness' | 'security' | 'cost' | 'hygiene' | 'policy';
+  message: string;       // what is wrong, specific to this occurrence
+  help?: string;         // what to do instead, from the rule
+  file: string;          // absolute path
+  display: string;       // repo-relative (or ~/) path for humans
+  line: number;          // 1-based
+  column?: number;
+  configPath?: string;   // e.g. "permissions.allow[0]"
+  snippet?: string;      // offending value, secrets redacted
+}
+```
+
+Findings are pre-sorted by severity, then file, then line.
+
+## Lower-level building blocks
+
+All exported from the package root:
+
+- `discover(root, { includeUserScope, home })` — collects and parses every config file, with
+  per-value source positions. Never opens credential files.
+- `lint(workspace, { rules, disabled, minSeverity, baseline })` — runs rules over a discovered
+  workspace. Pass your own `rules` array to run a custom subset or add your own rules.
+- `fingerprint(finding)` — the stable identity used by baselines. Anchored to the offending
+  value, then config path, then message hash — never line numbers.
+- `allRules`, `CATEGORIES` — the catalogue.
+- `loadPolicy(root, explicitPath?)` — reads `agentdoctor.policy.json`.
+- `helpers` — utilities handed to rules: `parsePermission`, `estimateTokens`, position lookup.
+
+## Writing a custom rule
+
+A rule is a plain object; `lint` accepts any array of them.
+
+```js
+import { discover, lint, allRules, helpers } from '@jqntn/agentdoctor';
+
+const noOpusInProjects = {
+  id: 'org/no-opus-model',
+  category: 'policy',
+  severity: 'warning',
+  title: 'Project pins an Opus-tier model',
+  help: 'Our org standard is sonnet for project config; sessions can override per run.',
+  check({ files, report, helpers }) {
+    for (const file of files) {
+      if (file.kind !== 'settings' || file.data?.model !== 'opus') continue;
+      const position = helpers.at(file, 'model');
+      report({ file, line: position.line, column: position.column,
+               configPath: 'model', message: 'model is pinned to opus.' });
+    }
+  },
+};
+
+const workspace = discover(process.cwd(), { includeUserScope: false });
+const result = lint(workspace, { rules: [...allRules, noOpusInProjects] });
+```
+
+The `check` function receives `{ workspace, files, report, helpers }`. Throwing inside a rule
+does not crash the run — it surfaces as an `internal/rule-crashed` warning finding.
+
+## Stability
+
+The exported API surface is small on purpose: `run`, `discover`, `lint`, `fingerprint`,
+`allRules`, `CATEGORIES`, `loadPolicy`, `helpers`, `VERSION`. Anything not exported from the
+package root is internal and may change without notice.

package/docs/architecture.md

@@ -0,0 +1,90 @@
+# Architecture
+
+Four stages, each a plain module with no dependencies: **discover → parse → lint → report**.
+
+```
+bin/agentdoctor.js        CLI: flags, exit codes, EPIPE handling
+src/
+  discover.js             finds config files; never opens credential files
+  parse.js                position-tracking JSON + frontmatter parsers
+  engine.js               runs rules, suppression, baselines, fingerprints
+  rules/
+    correctness.js  (26)  config the harness silently ignores
+    security.js     (22)  config that widens the execution surface
+    cost.js          (8)  always-on context, priced with stated assumptions
+    hygiene.js       (8)  config that confuses the next person
+    policy.js        (8)  team standards from agentdoctor.policy.json
+  report/
+    terminal.js  json.js  sarif.js
+```
+
+## Discovery
+
+`discover()` walks the project for every file the agent harness reads: settings at three
+scopes (project, local, user), `.mcp.json`, memory files at any depth, agents, skills,
+commands, hooks, keybindings. Vendor directories (`node_modules`, `dist`, `.venv`, …) are
+skipped, walk depth is capped, and files over 4 MB are recorded as skipped rather than read.
+
+Two properties are deliberate and load-bearing:
+
+- **Credential files are never opened.** `.credentials.json`, `.netrc`, private keys are
+  excluded by *path* before any `readFile`, and a test asserts a tripwire value planted in a
+  credentials file can never reach output. A security tool's own behavior is part of its
+  threat model.
+- **No network calls, ever.** Not for updates, not for telemetry. The entire run is local
+  file reads.
+
+## Position-tracking parsing
+
+Findings are only actionable if they point at a line, so agentdoctor does not use
+`JSON.parse`. `src/parse.js` is a hand-written JSON parser that records the `line:column` of
+every value, keyed by config path (`permissions.allow[0]`). It is also deliberately tolerant:
+trailing commas and comments — common in hand-edited config — parse fine, so one stray comma
+yields real findings instead of a single parse error. A genuinely broken file becomes a
+`correctness/invalid-json` **error**, because the harness ignores the entire file in that
+case, including any permission rules in it.
+
+Agent and skill definitions carry config in YAML frontmatter. The frontmatter parser supports
+the documented subset (scalars, inline and dash lists, one nesting level) rather than taking a
+YAML dependency.
+
+## The rule engine
+
+A rule is a plain object: `{ id, category, severity, title, help, check() }`. The engine calls
+each rule with the workspace and a `report()` callback, then handles everything rules should
+not re-implement:
+
+- **Suppression** — inline `agentdoctor-disable` comments, `--disable`, `--only`,
+  `--min-severity`, and baselines all apply centrally.
+- **Fingerprints** — each finding gets a stable identity anchored to the offending value,
+  then config path, then message hash. Never line numbers: a baseline must survive unrelated
+  edits ([why](baselines.md)).
+- **Crash isolation** — a throwing rule becomes an `internal/rule-crashed` warning; it cannot
+  take the run down.
+- **Ordering** — findings sort by severity, file, line, so output is deterministic.
+
+## Design principles
+
+1. **False positives are worse than false negatives.** A linter that cries wolf gets
+   uninstalled, at which point it catches nothing. The test suite contains a fully
+   well-configured fixture project that must produce **zero** findings; any rule that fires on
+   it is wrong by definition.
+2. **Every finding says why and what to do.** `message` states the specific problem; `help`
+   states the fix and the reasoning. `--explain <rule-id>` prints the full rationale.
+3. **Silent failure is the enemy.** The highest-value rules are the ones that catch config
+   the harness ignores without any error: misspelled hook events, deny rules naming
+   nonexistent tools, hooks pointing at missing scripts.
+4. **Zero dependencies, permanently.** This tool warns about supply-chain risk in MCP
+   servers; its own `npm install` footprint is part of the product. The JSON parser, YAML
+   subset, ANSI styling, and SARIF writer are all in-tree.
+5. **Estimates state their assumptions.** Cost rules price always-on context using a model
+   that accounts for prompt caching, and say so in the message. The token count is the fact;
+   the money is a model.
+
+## Testing
+
+`node --test`, no framework. The suite covers every rule (a meta-test fails if a rule id
+appears in no test file), parser positions, discovery, baselines (insertion-stability
+regression tests), CLI behavior including piping and exit codes, and docs consistency — the
+README's rule counts are asserted against the actual catalogue so marketing copy cannot drift
+from the code.

package/docs/baselines.md

@@ -0,0 +1,56 @@
+# Baselines: adopting agentdoctor on an existing repo
+
+An established project will have findings on day one. Fixing all of them before turning on CI
+enforcement is how adoption dies. A baseline records the current findings as accepted, so CI
+fails only on **new** problems.
+
+## Workflow
+
+```sh
+# once, reviewed and committed like any other change
+agentdoctor --no-user --write-baseline .agentdoctor-baseline.json
+git add .agentdoctor-baseline.json
+
+# in CI, from then on
+agentdoctor --no-user --baseline .agentdoctor-baseline.json
+```
+
+Fix things over time, then shrink the baseline by regenerating it:
+
+```sh
+agentdoctor --no-user --write-baseline .agentdoctor-baseline.json
+```
+
+The file is plain JSON — a list of finding fingerprints — so shrinkage is visible in diffs and
+code review. A growing baseline is a red flag a reviewer can see.
+
+## Why baselines survive edits
+
+A baseline that breaks when someone inserts an unrelated line is a baseline people stop
+trusting. agentdoctor anchors each fingerprint to the most stable identity available, in order:
+
+1. **The offending value itself** (e.g. the text of the permission rule). Permission rules
+   live in arrays, so a positional anchor like `permissions.allow[0]` changes meaning the
+   moment anyone inserts a rule above it. The rule text does not.
+2. **The config path**, for structural findings with no single value (an empty deny list, a
+   missing required key).
+3. **A hash of the finding's message**, for whole-file findings.
+
+Line numbers are never part of the identity. Concretely:
+
+- Insert a new (bad) rule anywhere in the allow list → exactly one new finding surfaces.
+- Add unrelated keys above the offending line → nothing resurfaces.
+- Fix a finding → its fingerprint disappears on the next `--write-baseline`.
+
+Each of these is a regression test in the suite (`test/baseline.test.js`).
+
+## Baselines vs inline suppression
+
+| | Baseline | `agentdoctor-disable` comment |
+|---|---|---|
+| Scope | Whole project, one file | One rule, one file |
+| Visibility | A count in every summary + a diffable JSON file | A comment next to the code |
+| Use for | The adoption backlog | A deliberate, permanent exception |
+
+Rule of thumb: baselines are for *debt*, inline suppressions are for *decisions*. If you find
+yourself regenerating the baseline to absorb new findings, you have turned the fire alarm off.

package/docs/ci.md

@@ -0,0 +1,87 @@
+# Running agentdoctor in CI
+
+## GitHub Actions, as code scanning annotations
+
+Findings appear inline on the pull request diff.
+
+```yaml
+name: agentdoctor
+
+on: [pull_request]
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+
+      # continue-on-error so the SARIF still uploads when findings exist;
+      # the gate job below is what actually fails the build.
+      - run: npx @jqntn/agentdoctor --no-user --sarif > agentdoctor.sarif
+        continue-on-error: true
+
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: agentdoctor.sarif
+
+      - name: Fail on errors
+        run: npx @jqntn/agentdoctor --no-user --quiet
+```
+
+`--no-user` matters in CI: there is no `~/.claude` on a runner, and scanning it locally would
+report findings a reviewer cannot act on.
+
+## Any other CI
+
+```sh
+npx @jqntn/agentdoctor --no-user --json > agentdoctor.json   # exit 1 if errors exist
+npx @jqntn/agentdoctor --no-user --max-warnings 0            # also fail on warnings
+```
+
+Exit codes are the contract:
+
+| Code | Meaning |
+|---|---|
+| 0 | No errors (and warnings within `--max-warnings`) |
+| 1 | At least one error, or too many warnings |
+| 2 | Bad usage: unknown flag, missing path, unreadable baseline |
+
+## Adopting on a repo that already has findings
+
+Fail on new problems without having to fix the backlog first:
+
+```sh
+# once, on a green-ish commit
+npx @jqntn/agentdoctor --no-user --write-baseline .agentdoctor-baseline.json
+git add .agentdoctor-baseline.json
+
+# in CI, from then on
+npx @jqntn/agentdoctor --no-user --baseline .agentdoctor-baseline.json
+```
+
+Baseline entries are fingerprints of `rule id + file + config path`, so moving a rule within a
+file keeps it suppressed, while adding a genuinely new one does not.
+
+Shrink the baseline as you fix things:
+
+```sh
+npx @jqntn/agentdoctor --no-user --write-baseline .agentdoctor-baseline.json
+```
+
+## Enforcing one standard across many repos
+
+Commit the same `agentdoctor.policy.json` to every repo, or fetch it from a central location in
+CI, and the policy rules hold each repo to it:
+
+```yaml
+      - run: curl -sSf https://internal.example.com/agentdoctor.policy.json -o agentdoctor.policy.json
+      - run: npx @jqntn/agentdoctor --no-user --quiet
+```
+
+The policy rules activate on the presence of the file — nothing else to configure.

package/docs/configuration.md

@@ -0,0 +1,115 @@
+# Configuration
+
+agentdoctor needs no config file to run. Everything is a CLI flag, an inline comment, or (for
+team standards) an `agentdoctor.policy.json`.
+
+## CLI reference
+
+### Output
+
+| Flag | Effect |
+|---|---|
+| *(default)* | Human-readable report, colored when stdout is a TTY |
+| `--json` | Machine-readable findings on stdout ([format](output.md)) |
+| `--sarif` | SARIF 2.1.0 for GitHub code scanning and other CI |
+| `--quiet`, `-q` | Print nothing; rely on the exit code |
+| `--no-color` / `--color` | Force color off/on (also honours `NO_COLOR` and `FORCE_COLOR`) |
+
+### Scope
+
+| Flag | Effect |
+|---|---|
+| `[path]` | Project root to audit (default: current directory) |
+| `--no-user` | Skip `~/.claude`. Recommended in CI, where user scope does not exist |
+| `--only <cat,...>` | Run only these categories or rule ids |
+| `--disable <id,...>` | Skip specific rules or whole categories |
+| `--min-severity <level>` | `error`, `warning`, or `info` (default) |
+
+Categories: `correctness`, `security`, `cost`, `hygiene`, `policy`.
+
+```sh
+agentdoctor --only security,correctness
+agentdoctor --disable cost/no-cleanup-period,hygiene
+agentdoctor --min-severity warning
+```
+
+### CI
+
+| Flag | Effect |
+|---|---|
+| `--max-warnings <n>` | Exit 1 if more than n warnings (errors always exit 1) |
+| `--baseline <file>` | Suppress findings recorded in the baseline ([guide](baselines.md)) |
+| `--write-baseline <file>` | Record current findings as accepted |
+
+### Team policy
+
+| Flag | Effect |
+|---|---|
+| `--policy <file>` | Policy file path (default: `agentdoctor.policy.json` at the root) |
+| `--init-policy` | Write a starter policy file ([guide](policy.md)) |
+
+### Adopt & share
+
+| Flag | Effect |
+|---|---|
+| `--init-ci` | Write `.github/workflows/agentdoctor.yml`: SARIF annotations + exit-code gate. Refuses to overwrite. |
+| `--init-skill` | Install the config-audit skill (SKILL.md + fix recipes) for Claude Code. Refuses to overwrite. |
+| `--init-agents` | Add a marked audit section to `AGENTS.md` for Codex, Cursor, Gemini CLI and every other tool that reads it. Creates or appends; refuses to duplicate. |
+| `--badge` | Print README markdown for a badge showing the current grade |
+| `--share` | Print a paste-ready score card: grade, counts, top rule ids. Never includes messages, paths, or snippets, so it is safe to share from private repos. Always exits 0. |
+
+### Introspection
+
+| Flag | Effect |
+|---|---|
+| `--list-rules` | The full catalogue (add `--json` for machine-readable) |
+| `--explain <rule-id>` | What a rule checks, why it matters, how to suppress it |
+| `--version`, `--help` | The usual |
+
+## Suppressing a rule for one file
+
+Put a comment anywhere in the offending file:
+
+```
+// agentdoctor-disable security/hook-unpinned-path
+```
+
+In JSON config, a comment works (agentdoctor's parser tolerates comments) — or use a string
+key that contains the directive:
+
+```json
+{
+  "// agentdoctor-disable security/hook-unpinned-path": "hooks come from vendored bin/",
+  "hooks": { }
+}
+```
+
+Accepted forms:
+
+- `agentdoctor-disable <rule-id>` — one rule
+- `agentdoctor-disable <category>` — a whole category
+- `agentdoctor-disable all` — everything, for this file
+- Multiple ids separated by commas or spaces
+
+Suppressions are file-scoped by design: a suppression you can see next to the code it affects
+is one a reviewer can question.
+
+To mark a credential-looking string as a deliberate placeholder:
+
+```
+agentdoctor-allow-secret
+```
+
+on the same line as the value.
+
+## Precedence
+
+1. `permissions.deny`-style hard skips: credential files are never read, regardless of flags.
+2. `--only` narrows the rule set first.
+3. `--disable` removes rules or categories from whatever `--only` left.
+4. Inline `agentdoctor-disable` comments suppress findings per file.
+5. `--baseline` suppresses previously accepted findings.
+6. `--min-severity` filters what is left.
+
+Suppressed counts are always reported in the summary, so a silenced finding is visible as a
+number even when its detail is not.

package/docs/faq.md

@@ -0,0 +1,83 @@
+# FAQ
+
+## Is my config uploaded anywhere?
+
+No. agentdoctor makes zero network calls — no telemetry, no update checks, no license pings.
+The entire run is local file reads. It also never opens credential files
+(`.credentials.json`, `.netrc`, private keys); they are excluded by path before anything
+reads them, and the summary reports how many were skipped.
+
+## Why did it find nothing?
+
+Probably because your config is small. A 10-line `settings.json` with two permission rules
+has little to get wrong, and agentdoctor is deliberately quiet on healthy setups — the test
+suite asserts zero findings on a well-configured project. The findings density rises with
+hooks, MCP servers, subagents, skills, and memory files.
+
+## Isn't this just a JSON schema?
+
+A schema catches type errors. It cannot tell you that `Bash(*)` is a bad idea, that your hook
+script does not exist on disk, that your deny rule names a tool that does not exist (and
+therefore blocks nothing), or that your `CLAUDE.md` costs real money per month. Most of the
+catalogue is semantic, not structural.
+
+## Why do you report warnings on things that are technically legal?
+
+Because the failure mode this tool exists for is config that is *legal and inert*. A
+misspelled hook event is valid JSON. It just never fires, and nothing tells you. When
+agentdoctor is unsure, it says `info`; when something is legal but almost certainly not what
+you meant, `warning`; when a guardrail provably does nothing or a real hazard is
+pre-approved, `error`.
+
+## A rule fired on something intentional. What now?
+
+Suppress it where it fired, visibly:
+
+```
+// agentdoctor-disable security/hook-unpinned-path
+```
+
+If you believe the rule is wrong in general, that is a bug — false positives are treated as
+more severe than false negatives. Open an issue with the config that triggered it.
+
+## How accurate are the cost estimates?
+
+The token counts are direct estimates from file size. The money figures are a *model*, and the
+message says so: they assume the memory file stays prompt-cached (it sits at the front of the
+prompt, which is exactly the content that caches) and state the request volume they assume.
+The uncached worst case is also shown where it matters. Assumptions live in
+`src/rules/cost.js` where you can disagree with them.
+
+## Does it modify my config?
+
+No. agentdoctor reports; you decide. Every finding includes what to change and why, but the
+edit is yours. The only file it ever writes is a baseline, and only when you pass
+`--write-baseline`.
+
+## Which harnesses does it understand?
+
+The `.claude/` configuration surface (Claude Code and compatible tooling), `.mcp.json` MCP
+server definitions, and the `CLAUDE.md`/`AGENTS.md` memory-file convention. The rule engine is
+harness-agnostic — discovery is the only layer that knows file layouts — so support for other
+agent config formats is an issue away.
+
+## Does it work on Windows?
+
+Yes, with one deliberate gap: the two rules that inspect file permissions
+(`security/world-writable-config` and the permission half of
+`security/hook-script-not-executable`) do nothing on Windows. Node synthesizes POSIX mode bits
+there — every file reports `0666` — so the check would fire on everything while telling you
+nothing. Windows ACLs are a different model than this rule can speak to. Every other rule
+behaves identically across Linux, macOS and Windows, and paths in output always use forward
+slashes so a baseline recorded on one platform matches on another.
+
+## Why Node 20+? Why zero dependencies?
+
+Node 20 is the oldest LTS with everything the tool needs built in. Zero dependencies is a
+security decision, not an aesthetic one: a tool that warns you about unpinned supply chains
+should not install one.
+
+## Can I use it as a library?
+
+Yes — `import { run } from '@jqntn/agentdoctor'` and you get structured findings. See the
+[API docs](api.md), including how to add organisation-specific rules.

package/docs/getting-started.md

@@ -0,0 +1,99 @@
+# Getting started
+
+## Requirements
+
+Node 20 or newer. Nothing else — agentdoctor has zero dependencies and installs no transitive
+packages.
+
+## Run it
+
+No install needed:
+
+```sh
+npx @jqntn/agentdoctor
+```
+
+Or install it:
+
+```sh
+npm install -g @jqntn/agentdoctor     # global CLI
+npm install -D @jqntn/agentdoctor    # per-project, for CI
+```
+
+By default it audits the current directory plus your user-level config in `~/.claude`. To audit
+a specific project, pass the path:
+
+```sh
+agentdoctor path/to/repo
+agentdoctor --no-user          # project config only (use this in CI)
+```
+
+## What gets scanned
+
+| File | What it is |
+|---|---|
+| `.claude/settings.json` | Project settings: permissions, hooks, env, model |
+| `.claude/settings.local.json` | Personal overrides (should be gitignored) |
+| `~/.claude/settings.json` | User-level settings |
+| `.mcp.json` | MCP server definitions |
+| `CLAUDE.md`, `CLAUDE.local.md`, `AGENTS.md` | Memory files, at any depth |
+| `.claude/agents/*.md` | Subagent definitions |
+| `.claude/skills/*/SKILL.md` | Skill definitions |
+| `.claude/commands/*.md` | Slash commands |
+| `.claude/hooks/*` | Hook scripts (existence and permissions only) |
+| `.claude/keybindings.json` | Key bindings |
+
+**Never scanned:** `.credentials.json`, `.netrc`, private keys. These are skipped by path
+before anything opens them, and the summary reports how many files were skipped. agentdoctor
+also makes no network calls — nothing leaves your machine.
+
+## Reading a finding
+
+```
+.claude/settings.json
+  4:7     error  "Bash(*)" auto-approves every shell command, including ones
+                 you have not seen.
+                 | Bash(*)
+                 -> Replace the wildcard with the specific commands you actually
+                    want unattended, e.g. "Bash(npm test:*)".
+                 security/unrestricted-bash
+```
+
+Top to bottom: file, `line:column`, severity, what is wrong, the offending value, what to do
+instead, and the rule id. Every rule id works with `--explain`:
+
+```sh
+agentdoctor --explain security/unrestricted-bash
+```
+
+## The grade
+
+Every report ends with a health grade - `A+` (zero findings), `A` (info only), `B`/`C`
+(warnings), `D`/`F` (errors). It is computed from what is actionable today, so fixing or
+deliberately suppressing findings raises it. `agentdoctor --share` prints a paste-ready
+score card (rule ids and counts only - safe to share from private repos), and
+`agentdoctor --badge` emits README markdown for it.
+
+## Severities
+
+| Severity | Meaning |
+|---|---|
+| `error` | Broken or dangerous. A guardrail that does not work, a pre-approved destructive command, a committed credential. |
+| `warning` | Very likely a problem, occasionally intentional. |
+| `info` | Worth knowing; act on it or ignore it. |
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | No errors (and warnings within `--max-warnings`, if set) |
+| 1 | At least one error, or too many warnings |
+| 2 | Bad usage: unknown flag, missing path, unreadable baseline |
+
+## Next steps
+
+- [Configuration](configuration.md) — every flag, suppression, disabling rules
+- [CI setup](ci.md) — SARIF annotations, exit-code gating
+- [Baselines](baselines.md) — adopting agentdoctor on a repo that already has findings
+- [Team policy](policy.md) — holding many repos to one standard
+- [Rule reference](rules.md) — all 72 rules and the reasoning behind each