CLAUDE.md git:20260714.8273d3fA

Immutable. This exact content never changes and is served at /api/v1/blob/b06c2a07cfd6ab06.

# llmwiki

A knowledge compiler CLI. Raw sources in, interlinked wiki out.

## Development Guidelines

### Code Style & Standards

- Code files (TypeScript, Python, JavaScript, shell, SQL) must be smaller than 400 lines excluding comments. Once 400 is exceeded, initiate a refactor. **Markdown and other prose/config files (`.md`, `.mdx`, `.yaml`, `.json`, `.toml`) are exempt** — long planning documents, roadmaps, and reference catalogs are allowed to grow as substance requires.
- Functions must be smaller than 40 lines excluding comments and the catch/finally blocks of try/catch sections. If a function exceeds that, refactor it.
- test files must be smaller than 400 lines excluding comments. Once 400 is exceeded, split the tests into multiple files.
- tests must be smaller than 40 lines excluding comments and the catch/finally blocks of try/catch sections. If a test exceeds that, refactor it, or separate it into multiple tests.


### clean code rules

- Meaningful Names: Name variables and functions to reveal their purpose, not just their value.
- One Function, One Responsibility: Functions should do one thing.
- Avoid Magic Numbers: Replace hard-code values with named constants to give them meaning.
- Use Descriptive Booleans: Boolean names should state a condition, not just its value.
- Keep Code DRY: Duplicate code means duplicate bugs. Try and reuse logic where it makes sense.
- Avoid Deep Nesting: Flatten your code flow to improve clarity and reduce cognitive load.
- Comment Why, Not What: Explain the intention behind your code, not the obvious mechanics.
- Limit Function Arguments: Too many parameters confuse. Group related data into objects.
- Code Should Be Self-Explanatory: Well-written code needs fewer comments because it reads like a story.

### Comments and Documentation

- include a substantial JSDoc comment at the top of each file. For python files, use google style docstrings
- Write clear comments for complex logic
- Document public APIs and functions
- Use JSDoc comments for functions
- Keep comments up-to-date with code changes
- Document any non-obvious behavior

### Internal Documentation Routing

- `localdocs/` is retired as a write location. Do not create, restore, or modify a `localdocs/` directory in this repository or any of its worktrees.
- Any legacy `localdocs/` copy kept in a gitignored archive is historical only. Do not search for, read, cite, or update it unless the user explicitly asks for archive recovery or comparison.
- The canonical tracked home for every internal document that would previously have been written under `localdocs/` is `/Users/ethan/projects/supernet/atomicmemory/am-research-internal/docs/llm-wiki-compiler`.
- Preserve the path below `localdocs/` when routing a document. For example, `localdocs/plans/example.md` maps to `/Users/ethan/projects/supernet/atomicmemory/am-research-internal/docs/llm-wiki-compiler/plans/example.md`.
- Read and update existing internal roadmaps, plans, specs, audits, reports, research, release notes, harness artifacts, and PRDs at that canonical location.
- Before writing there, read any applicable `AGENTS.md` files in the internal repository and inspect its git status so unrelated changes are preserved.
- If the canonical location is unavailable, stop and ask for direction. Do not fall back to `localdocs/`, another worktree, or an untracked copy.
- Public product documentation that belongs in this repository's tracked `docs/` tree remains here; this routing rule applies only to material that would previously have gone into `localdocs/`.

### Pre-Commit Checks

Before committing any work, and before considering any task complete, you must:

1. `npx tsc --noEmit` — type-check passes
2. `npm run build` — build succeeds
3. `npm test` — all tests pass
4. `fallow` — run the fallow codebase health analyzer. Fix all issues it reports (dead code, duplication, complexity). Use `fallow fix --dry-run` to preview auto-fixes, then `fallow fix --yes` to apply. Fix any remaining issues manually. Do not commit until fallow reports no issues.

## General Rules

- First think through the problem, read the codebase for relevant files.
- Make every task and code change you do as simple as possible. We want to avoid making any massive or complex changes. Every change should impact as little code as possible. Everything is about simplicity.
- Never speculate about code you have not opened. If the user references a specific file, you MUST read the file before answering. Make sure to investigate and read relevant files BEFORE answering questions about the codebase. Never make any claims about code before investigating unless you are certain of the correct answer - give grounded and hallucination-free answers.