CLAUDE.md git:20260911.61ebbadA

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

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. Shared cross-agent rules live in `AGENTS.md`; this file adds the Claude Code specifics.

## What This Repo Is

A hostile audit toolkit shipped as **one skill** — `nitpicker` — invoked as
`/nitpicker <command> [extra instructions]`.

The router is `skills/nitpicker/SKILL.md`. Each command's instructions live in
`skills/nitpicker/commands/<command>.md`, with shared conventions in
`commands/_conventions.md`.

The repo is installable as a Claude Code plugin via `/plugins`, and into
Copilot, pi and other agents via `npx skills add ivuorinen/skills` (open Agent
Skills format). Internal dev skills — scaffolding, validation, release — live
under `.claude/skills/` and are not shipped to consumers.

## Context Discipline

`_conventions.md` carries only what binds every command. Four protocols load on a
trigger instead — `_findings-store` before the first store operation,
`_committing` before a commit, `_documentation` before a fix or a `docs` finding,
`_audit-coverage` for `audit`. Each trigger is stated in `_conventions.md` and in
SKILL.md's execution order, and both are binding: a protocol not loaded is a
protocol not followed. Rules that hold in *every* run — the finding contract,
redaction, the migration consent gate, the run protocol's shape — stay in the
core file rather than moving with their protocol.

`scripts/context_pack.py` (MCP: `np_context_pack`) is the portable context
firewall. It answers with coordinates — path, line range, enclosing symbol, why
it matched — not with file bodies. Its modes are the acquisition ladder:
`inventory` (A), `symbols` and `diff` (B), `evidence` (C). Level D is a direct
read the caller performs after the pack narrows it. The invariant the callers
are held to: **compression may decide what to inspect next; only original source
may prove a finding.** `--self-test` runs the known-positive controls, because a
retriever returning nothing is otherwise indistinguishable from a repository
containing nothing.

`scripts/check-context-tokens.py` reports the size of the set loaded on every
turn and of one invocation. It is CLI-only and **cannot fail a build**: its
numbers are four-characters-per-token estimates, and gating on an estimate turns
an approximation into a rule nobody can reproduce. Read the `--baseline` delta,
not the absolute. `check-agent-instructions.py` remains the directive-count gate;
the two measure different halves of the same budget.

## Development Commands

```bash
make check        # the full gate; run before every commit. `make help` lists its targets
make validate     # SKILL.md + command-file structure (public + internal)
make validate-evals # evals/evals.json + evals/trigger-queries.json shape per skill
make ring-deps    # print the module dependency graph; fail on an outward (inner→outer) edge
make test         # run pytest unit tests
make list         # list the skill and its commands
make lint         # ruff check on scripts/, tests/, skills/
make format       # ruff format on scripts/, tests/, skills/
make security     # bandit scan of skills/ and scripts/ (config in [tool.bandit])
make opengrep     # opengrep scan (the rules Codacy reports) + stale-suppression check
```

## Commands

The authoritative command listing (categorized, with aliases) is `## Commands` in `skills/nitpicker/SKILL.md`; `/nitpicker help` prints it. The 1.x standalone skill names (`security-auditor`, `test-auditor`, …) are aliases of the new short names (`security`, `tests`, …).

## Agent Skills Spec Compliance

The normative format is the open spec at <https://agentskills.io/specification>.
`scripts/validate-skill.py` enforces it. Required: `name` (≤64 chars,
lowercase/digits/hyphens, no leading, trailing or consecutive hyphen, matching
its directory) and `description` (≤1024 chars). Optional: `license`,
`compatibility` (≤500 chars), `metadata` (a string→string map) and
`allowed-tools` (one space-separated string).

A top-level key outside that set is an **error**. Client-specific properties go
under `metadata`, which is what the spec designates it for. There is no
allowlist and no exemption; internal dev skills are held to the same rule. Body
size warns past 500 lines or ~5000 tokens, the progressive-disclosure
instructions tier.

`disable-model-invocation` therefore lives under `metadata` as `"true"`, quoted
because metadata values are strings. Claude Code reads that key from the top
level only, so under `metadata` it is inert and those skills become
model-invocable. That trade was accepted deliberately, buying portability.

Each skill's eval sets live in `<skill-dir>/evals/` — `evals.json` (output-quality cases with gradable assertions) and `trigger-queries.json` (description trigger accuracy, fixed train/validation split) — gated by `make validate-evals`. See `.claude/rules/skill-official-best-practices.md`.

`make spec-check` cross-checks every skill against the Agent Skills reference
validator. It needs network access, so it sits outside `make check`;
`validate-skill.py` enforces the same constraints offline. Every skill passed at
the time of writing, internal dev skills included — re-run it rather than
trusting that, since a spec release can change the verdict.

Three install traps, each hit once already:

- The PyPI package is `skills-ref`, but its console script is `agentskills`.
  The spec page still documents a `skills-ref` command, which no longer exists
  and exits 1 with no output.
- The identically-named npm package is unrelated to Anthropic.
- Failures print to stderr and successes to stdout, so merge stderr before
  judging a run clean.

## Command File Format

- Only the router `skills/nitpicker/SKILL.md` has YAML frontmatter (`name`, `description` with "Use when", ≤1024 chars, single-quoted when it contains ": ", plus `license` and `compatibility`).
- Command files have no frontmatter. Required shape: h1 `# /nitpicker <command> — <Title>` (must match the filename), a `## When to use` section, no header-level jumps. Enforced by `scripts/validate-skill.py`.
- Every command file in `commands/` whose name does not begin with `_` needs a
  row in one of SKILL.md's command tables (`## Commands` or
  `## Internal commands`), 1:1, enforced by `scripts/validate-skill.py`.
  Shared files prefixed `_` (`_conventions.md`, `_audit-coverage.md`) are the
  exception, and carry no row.
- Never duplicate `_conventions.md` content (severity table, findings protocol, generic rules) into a command file.
- No behavioral reliance on Claude-only features (`$ARGUMENTS`, `argument-hint`): arguments are parsed from the free text after the invocation so the skill works in Copilot and pi.

## Findings Store

One file per **open** finding under
`docs/audit/findings/<auditor>/open/<id>.md`. Resolving one appends a record to
the append-only `docs/audit/findings/resolved.jsonl` ledger and deletes the open
file, so the tree does not accumulate hundreds of resolved files.

`INDEX.md` is generated: the index (rebuilt by findings.py and by the
PostToolUse hook below) is tool output, not a file to hand-edit. An in-store
`.gitattributes`, self-written by findings.py, marks the store
`linguist-generated` so audit runs don't flood PR diffs.

The store is managed through the `np_*` MCP tools where the session exposes
them, else the shipped, stdlib-only CLI. `commands/_findings-store.md` maps
every operation to its interface and names the ones no tool wraps. Read it
there rather than keeping a second list here — that is how this paragraph came
to name three of the five.

```bash
python3 skills/nitpicker/scripts/findings.py --help    # every subcommand
```

IDs are content-hashed rather than hand-assigned. `new --force` re-opens a
resolved finding under the id it already had, dropping its ledger record; that
is the one route by which an id in the ledger comes back.

`migrate` converts 1.x `docs/audit/*-findings.md` documents. `migrate-resolved`
folds a legacy `<auditor>/resolved/*.md` tree into the ledger.

`export --format sarif|json|junit` (in `findings_export.py`) renders the store
for another system. The Static Analysis Results Interchange Format (SARIF) —
what a code-scanning UI ingests — omits resolved findings, since an alert on a
fixed defect is indistinguishable from a live one. JUnit maps open to failure
and resolved to pass, so a CI panel shows unfixed findings beside failing tests.

`new --location path:START-END` records where the evidence was read — START (the
first cited line) and END (the last) — plus a fingerprint of that source.
`recheck` re-computes every one, so `reverify` can skip a finding whose cited
bytes are unchanged rather than spend a model pass on it.

The fingerprint covers the cited line range, so an unrelated edit *above* it
reads as `changed`. That is the safe direction: it costs a re-check rather than
a missed change. `location` is deliberately outside the content-hashed id.

The PostToolUse hook `validate-audit-findings-hook.py` validates edited open
findings and the ledger, and regenerates the index.

## PR Fetchers

`cr` reads a PR's review surface through two entry points —
`fetch-pr-comments.py` and `fetch-pr-status.py` — that cover GitHub, GitLab and
Bitbucket Cloud behind **one** JSON format. Both are thin: they resolve their
sibling directory and delegate to `pr_cli.run_cli`, which parses the argument
forms and maps exceptions to the 0/1/2 exit contract.

`pr_common.py` is the **port**, and owns everything shared — git-remote parsing,
platform detection, the `Target` (platform + git host + project path, from which
the API base is derived), the credential-pinned HTTP layer, both pagination
styles, the output envelopes, and `provider_for` dispatch. One provider module
per platform (`pr_github.py`, `pr_gitlab.py`, `pr_bitbucket.py`) exposes exactly
`fetch_comments(target, n)` and `fetch_status(target, n)`.

`pr_cli.py` is the CLI **driving adapter** and is deliberately not part of that
port: argv parsing, stdout rendering and exit codes are facts about running as a
command, and `pr_common` is imported by all three providers and by
`mcp_server.py` — the other driving adapter — none of which run as this CLI.
Keeping the two apart is what lets `pr_common` stay the library its docstring
claims. `make ring-deps` prints the resulting graph.

Two invariants make the shared format worth having, and both are pinned by
tests. A field a platform cannot supply is present and empty or null rather than
absent, so a caller reads every key unconditionally instead of branching on key
existence to learn which platform answered. And a credential is only ever sent
to the host it was declared for:
the redirect handler is built per-request with that host, every paginated URL is
re-validated before it is followed (both `Link` headers and body `next` fields
are server-controlled), and a token reaches only its platform's own public
host unless `GH_HOST`/`GITLAB_HOST` names the self-hosted one. Withheld by
default, declared by exception: gating on a *mismatch* instead would let the
unconfigured case through, since it declares no host to mismatch against.
Platform detection refuses an unrecognised host rather than guessing, since a
wrong guess is a credential handed to a third party.

The MCP (Model Context Protocol) tools `np_pr_comments` and `np_pr_status` wrap
the same providers. They are the only tools on the server carrying
`openWorldHint: true`, and their results are wrapped in an
`<untrusted-data source="pull-request">` envelope — PR bodies are written by
anyone who can comment on the PR. They are not the only enveloped tools:
`np_context_pack` and the findings readers carry their own `source` tags, since
repository paths and stored finding bodies are written by whoever wrote the
audited tree. SKILL.md's **Untrusted results** paragraph is the full list.

## Editing a shipped tool mid-session

The MCP server imports every shipped module it depends on once at startup and
holds them for the life of the process. `_LOADED` in `mcp_server.py` is the
authoritative list; it includes the hyphen-named `process-sarif.py` and
`check-rules-anatomy.py`, which reach it through `_load_bundled` rather than a
plain import and are easy to overlook. **Editing any module on that list does
not change what the running server executes.** Worse, two servers are
registered: `.mcp.json` starts one from the working tree, and
`.claude-plugin/plugin.json` starts one from `${CLAUDE_PLUGIN_ROOT}` — the
installed copy under `~/.claude/plugins/cache/`, which reflects only the
installed version, at any age.

So after editing anything under `skills/*/scripts/`, drive the findings store
through `python3 skills/nitpicker/scripts/findings.py` for the rest of the
session; it loads fresh every invocation. Restarting the session picks up the
new code.

`mcp_server.py` records each module's mtime at import and prefixes a `[warn]`
line to the result of every tool that writes (`np_new_finding`,
`np_resolve_finding`, `np_write_index`) when the file has since changed, or
when it is serving a different copy than the project has on disk. The read
tools carry no such prefix, so an edit to `process-sarif.py` or
`check-rules-anatomy.py` reaches you through the rule above and through nothing
else: `np_process_sarif` will consolidate a security scan with code that is not
on disk and say nothing. This is a backstop, not the control: the rule above is.

This is not hypothetical. A stale `redact()` wrote an unredacted credential into
`resolved.jsonl` during the audit that added the redaction, and only a
`detect-private-key` commit hook caught it — see `audit-9bc6eb39`.

## Script Execution

Two classes (see `.claude/rules/use-uv-runner.md`):

- **Shipped skill tools** (`skills/*/scripts/`): stdlib-only, plain `python3`, `#!/usr/bin/env python3`. The stdlib-only rule is enforced by `scripts/check-stdlib-only.py` (pre-commit + CI) — a third-party import fails the gate.
- **Internal dev tooling** (`scripts/`, `scripts/hooks/`, `tests/`): `uv run --quiet`, `#!/usr/bin/env -S uv run --quiet` + `# /// script` block.

Every shipped tool answers `--help`/`-h` with its interface on stdout at exit 0.
Structured data goes to stdout, diagnostics to stderr. Exit codes are distinct
per failure class: 0 success, 1 runtime or I/O error, 2 usage error.

Handle `--help` before any positional argument resolves as a path. Otherwise the
flag is read as input and the agent gets a path error in place of usage text.
The design rules live in `.claude/rules/use-uv-runner.md`; enforcement is author
discipline plus the per-tool `--help` tests.

## Suppression Markers

Two scanners run over `skills/` and `scripts/`, and each has its own marker:
`# nosec` for bandit, `# nosemgrep` for opengrep. `make opengrep` gates the
second, and `scripts/check-opengrep.py` is the tool.

opengrep is the scanner Codacy reports from, and its ruleset lived only in the
Codacy UI — so a finding was invisible from a checkout and reproducible only by
pushing. Two commits went to configuring bandit before the owner pointed out
which engine was actually reporting. `make opengrep` runs
`r/python.lang.security.audit`, the namespace that reproduces those findings
(`p/python` returns nothing here; it omits the `-audit` rule variants).

**A `# nosemgrep` marker only counts on the finding's own line or the line
directly above it.** One line further up is ignored silently — no warning, no
diff, the finding just quietly comes back. A reason comment therefore belongs
*above* the marker: one placed between the marker and the code separates the
two, and the suppression stops applying.

So the gate also runs a second pass with `--disable-nosem` and fails on any
marker that lines up with no revealed finding. That catches the misplaced marker
and the leftover one that outlived its call. Nothing else checks this; Codacy
does not.

Two things worth knowing before trusting a clean run:

- Staleness is judged only against the configured namespace, so suppressing a
  rule outside it means widening `CONFIG` first, or the marker reads as stale.
- Markers outside the scanned roots are judged neither way; the count is printed
  rather than passed over silently.

A scan error fails the gate. opengrep skips a file it cannot parse, so a parse
error means unscanned code, and reporting the remainder as clean would hide it.
This is also why the gate runs opengrep rather than semgrep: semgrep 1.172.0
cannot parse a `match` statement and drops the whole file, and this repo uses
them.

Locally the target skips when opengrep is absent; under CI it fails instead,
because a gate that skips silently is not a gate. The `Validate` workflow
installs a version-pinned, digest-verified binary before `make check`.

## Adding a New Command

1. Use `/new-command` — it orchestrates the RED → GREEN → REFACTOR → adversarial-review → validate → pr-review cycle for a command file.
2. Create `skills/nitpicker/commands/<name>.md` (short kebab-case name, 2.0 vocabulary — no `-auditor` suffixes).
3. Add its row to the `## Commands` table in `skills/nitpicker/SKILL.md`, the Routing Guide in `.claude/skills/skills/SKILL.md`, and the command table in `README.md`. Update `.github/copilot-instructions.md` only if the new command changes its rules (it deliberately carries no command table).
4. `make check` must pass (the validator enforces table ↔ file sync).
5. Commit with `feat: add /nitpicker <name> command` (minor bump via release-please).

## Conventions

Skill and command writing style, lifecycle, and repo conventions live in
`.claude/rules/`.

How much of each rule is machine-enforced varies: several are gated only in
part, and some not at all. Each rule states its own enforcement. Read that
statement in the rule itself rather than assuming a rule here is gated end to
end.

- `skill-format.md`
- `skill-style.md`
- `counts-in-prose.md` (author discipline for counts; the neighbouring
  reference drift — stale paths, dead anchors, stale dates, placeholders — is
  gated by `check-rules-anatomy.py`)
- `instruction-budget.md` (gated by `check-agent-instructions.py`: every file a
  session loads each turn draws on one shared budget; the rule file names the
  command that reports the current total)
- `skill-lifecycle.md` (agent discipline; no gate)
- `skill-official-best-practices.md`
- `use-uv-runner.md`
- `github-actions-security.md`
- `use-context-mode.md`
- `commit-gate-integrity.md`
- `commit-types.md` (author discipline; the CI `commit-lint` job gates only the
  CI-only-diff-with-a-breaking-marker case)
- `write-surgical-code.md` (agent discipline; no gate)
- `snapshot-before-mutating.md` (partly gated: the hook covers direct Bash only,
  not a `git checkout --` inside a script)
- `vendored-skills.md`

## Plugin Metadata

| File                              | Purpose                                  |
| --------------------------------- | ---------------------------------------- |
| `.claude-plugin/plugin.json`      | Plugin name, version, author, keywords   |
| `.claude-plugin/marketplace.json` | Marketplace listing (used by `/plugins`) |

Version must stay in sync across `package.json`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `.release-please-manifest.json`, and `pyproject.toml`. Use `scripts/bump-version.py` for manual bumps; release-please handles it on CI.

`uv.lock` carries one more copy in its root `[[package]]` entry.
Neither `check-version-sync.py` nor release-please covers it — 3.0.0 shipped
with the lockfile still declaring 2.0.0. `make lock-check` gates it with
`uv lock --check`, uv's own staleness test, which also catches dependency drift.

Both bump paths keep it current. `bump-version.py` re-locks after writing the
manifests. On CI, the `sync-lockfile` job in `release-please.yml` commits the
regenerated lockfile onto the release PR, because release-please has no updater
for it.

Re-locking is best-effort rather than guaranteed. When `uv` is absent, times
out, or fails, `bump-version.py` reports the failure and continues instead of
aborting a bump whose manifests are already written. It names the recovery in
its output.

Run `uv lock` to resync — that is the supported way to move the version in the
lockfile. Hand-edit `uv.lock` only where uv cannot run at all, and treat that as
a stopgap: the next `uv lock` overwrites the value.

## Versioning

[Semantic Versioning](https://semver.org/) with [release-please](https://github.com/googleapis/release-please):

| Prefix                                | Effect                                      |
| ------------------------------------- | ------------------------------------------- |
| `feat:`                               | Minor bump (new command or feature)         |
| `fix:`                                | Patch bump (command improvement or bug fix) |
| `feat!:` / `BREAKING CHANGE:` footer  | Major bump                                  |
| `chore:`, `docs:`, `refactor:`, `ci:` | No bump                                     |

Merge to `main` → release-please opens a Release PR → merging it creates the GitHub Release and tag.

## Configuration

`.claude/settings.local.json` — local settings; gitignored.

`.claude/settings.json` — shared PostToolUse hooks on every Write/Edit:

- `validate-skill-hook.py` — validates SKILL.md structure on any edited SKILL.md or `commands/*.md` file
- `validate-json-hook.py` — validates JSON syntax on any edited `.json` file
- `check-version-sync-hook.py` — warns when a version file edit desyncs the version manifests
- `ruff-hook.py` — auto-fixes and lints any edited `.py` file
- `validate-audit-findings-hook.py` — validates files under `docs/audit/findings/` and regenerates `INDEX.md`
- `validate-rules-hook.py` — validates any edited `.claude/rules/*.md` file (`validate-rules.py` + `check-rules-anatomy.py`)
- `validate-evals-hook.py` — validates the eval set of any edited `skills/*/evals/*.json`

Plus a **Bash** PostToolUse hook, `post-bash-revalidate.py`: Write/Edit matchers
never see a Bash-mediated edit (`sed -i`, redirection, `git mv`), so this one
re-runs the whole-tree gates when `git status` shows a governed path dirty.

Plus the **PreToolUse** hooks below, which can *block* a tool call before it
runs — the most behaviour-changing entries in the file. `.claude/settings.json`
holds the authoritative list; `tests/test_settings.py` fails when one of them is
configured and unnamed here:

- matcher `Bash` — `deny-agents-path-hook.py`, which blocks a Bash command whose
  text names `.claude/agents/` **or a full protected agent filename** —
  literally, quoted, escaped, variable-built, or glob-spelled (the
  `permissions.deny` block binds file tools only, not Bash — it names `Read`,
  `Edit` **and** `Write` rules explicitly, rather than assuming an `Edit` rule
  also binds Write, which is undocumented client behaviour no in-repo gate can
  observe. `tests/test_settings.py` pins the exact list). So
  `find . -name release-readiness-reviewer.md -exec cat {} +` is blocked too.
  It raises the cost of reaching that tree; it does not close it. The guard
  matches tokens, so a command that locates the files by **content** rather than
  by path or name (`git ls-files | grep review | xargs cat`) carries neither
  token and passes — the one token it does carry, `review`, is a nitpicker
  command name that appears in ordinary commands constantly, so matching it
  would block routine work. Treat `.github/CODEOWNERS` plus branch protection as
  the binding control, not this hook. The same hook also blocks a Bash **write**
  to `scripts/hooks/` or `.claude/settings.json` (`PROTECTED_WRITE`), where
  reading stays allowed — so the enforcement surface cannot be edited around via
  `sed -i` or a redirect. Hand those edits to the owner rather than reaching for
  another spelling.
- matcher `Bash` — `deny-unsafe-git-hook.py`, which blocks `git` with
  `--no-verify` or `-n` (stacked clusters and the abbreviations git accepts
  included), a `-c core.hooksPath=`, `--config-env=` or `GIT_CONFIG_*` override
  that disables the repository's hooks, an alias whose body resolves to any of
  those (a `!` shell body included), and a push to a protected branch. It reads
  a command nested in `$(...)`, backticks or a subshell as its own stage, and
  looks through a wrapper (`env`, `sudo`, `xargs`, …) to the git call behind it.
  Per `.claude/rules/commit-gate-integrity.md` the pre-commit validators are not
  optional; commit without the flag and fix what fails. That rule also states
  what remains open — the guard matches command text, so a request carrying no
  `git` token at all (a shell function shadowing it, a script, `eval` on a
  runtime-built string) passes it.
- matcher `Bash` — `guard-ctx-ok-hook.py`, which validates the `# ctx-ok`
  escape hatch from `.claude/rules/use-context-mode.md` and denies it on any
  verb outside its allowlist, including every read verb. Fails closed on an
  unrecognised verb, so a denial usually means route the command through
  context-mode instead — not that the marker was spelled wrong.
- matcher `Bash` — `ask-destructive-restore-hook.py`, which asks before a
  `git checkout --` or `git restore` that would discard uncommitted tracked
  changes. See `.claude/rules/snapshot-before-mutating.md`: snapshot with `cp`
  instead.
- matcher `Bash` — `graphify hook-guard search`
- matcher `Read|Glob` — `graphify hook-guard read`

Each graphify guard opens `command -v graphify >/dev/null || exit 0`, so on a
clone without graphify installed it exits 0 and is a no-op. When graphify is on
the executable search path (`$PATH`), the guard's own exit code propagates and
can block the call.

Between those two it **pins the binary**: it compares `graphify --version`
against `.claude/skills/graphify/.graphify_version` and exits 2 on a mismatch.
Without that, a different or compromised `graphify` earlier on `$PATH` silently
takes over the permit/deny decision for every file read, glob and shell command
in the session — the one executing component the vendored-skill trust model left
unbound. An **empty or missing** pin file denies rather than passes: treating an
unreadable pin as "no constraint" would make deleting one file disable the check
in silence. The ceiling is worth knowing — a version string is self-reported, so
this raises the cost of substitution and makes an accidental mismatch visible;
it is not attestation.

Plus a Stop hook, `stop-reminder.py`, which reminds about pending skill files
before Claude hands back control. Its scope is the union of the git index
(`git diff --cached`), the working tree (`git diff`) and the untracked set
(`git ls-files --others`), so **unstaged** and brand-new files count too.

A `stop_hook_active` guard keeps the reminder from re-firing on the forced
continuation its own exit 2 causes. That is one stop cycle, not one session:
the reminder repeats once per turn for as long as skill edits stay
uncommitted. That is the observed behaviour, not a broken guard.

Every hook resolves the repo root as `CLAUDE_PROJECT_DIR` → `REPO_ROOT` → the computed parent of `scripts/hooks/`, in that order. `CLAUDE_PROJECT_DIR` is set by Claude Code; set `REPO_ROOT` only when running a hook manually outside Claude Code against a non-default tree.

`.claude/skills/nitpicker` is a symlink to `../../skills/nitpicker` so Claude Code discovers the shipped public skill alongside the internal dev skills.

## graphify

This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.

Rules:

- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).