[mBukator]

🎯 Overview

Restructures the agent docs around progressive disclosure. AGENTS.md shrinks to what every task needs and links the topic files with a "read when" trigger. The rule files stop contradicting the tooling and code. No rule loads in every Claude session any more: the always-loaded baseline drops from about 680 lines (AGENTS.md + naming.md + security.md) to the 62-line AGENTS.md.

Docs only. No source, test or config changes.

✨ Changes

Root AGENTS.md

Minimal root:

• One-sentence description, every-task rules (ESM .js imports, layer direction, no any in src/, hyphens, docs sync), the 6 security invariants, the non-standard commands plus the CI gate, and the git safety lines
• A "Read when relevant" table of plain markdown links (not @ imports, so CLAUDE.md's @AGENTS.md does not pull every file into context)
• Removed: the architecture tree (already in architecture.md), the hook details (already in git-workflow.md), formatting rules that Prettier and ESLint enforce, and standard npm scripts

Contradictions resolved

Docs now match the tooling and code:

• Line length: dropped the "under 100 characters" rule (.prettierrc enforces 90)
• any: banned in src/ only (ESLint turns no-explicit-any off for tests/**)
• Imports: lib→lib and utils→utils are allowed if they don't form a cycle, and utils may import side-effect-free packages like chalk (this is what the code already does)
• Coverage: the vitest.config.ts thresholds (80/80/80/75) are the rule. Removed the 100% targets and the false "enforced in CI" claim (CI does not run coverage)
• Config: both fixed locations (~/.merlinrc.json, <repo-root>/.merlinrc.json), and validateConfig drops invalid fields instead of throwing
• Mock placement gotcha: Vitest hoists vi.mock, so the gotcha now covers using vi.hoisted for variables a mock factory needs

Trimmed

Removed:

• Generic content any coding agent already knows: the DRY, KISS and SOLID primers, and long BAD/GOOD naming examples
• Stale content: the code statistics and current-size tables, and a "Node.js 20" example
• Duplicates: the release checklist (now a pointer to docs/development/releases.md)
• "Last Updated" stamps and Resources/References link lists
• About 70 single-quoted examples, converted to double quotes

🔧 Technical Details

Files Modified:

• 📝 AGENTS.md - 113 → 62 lines, links table
• 📝 CLAUDE.md - load table updated; guides are indexed from AGENTS.md
• 📝 .claude/rules/naming.md - 331 → 69 lines, now scoped to **/*.ts
• 📝 .claude/rules/security.md - 236 → 51 lines, now scoped to src/**/*.ts; keeps only what AGENTS.md doesn't say
• 📝 .claude/rules/{code-style,clean-code,commands,lib,utils,testing}.md - contradiction fixes and trims
• 📝 .claude/guides/{architecture,development,git-workflow}.md - stale tables, Mock Placement fix, link lists
• 📝 .claude/maintenance/codebase-map.md - coverage target
• 📝 docs/development/{architecture,contributing,testing}.md - import rules, any scope, coverage wording

📋 Testing

How to Test:

npx prettier --check ".claude/**/*.md" AGENTS.md CLAUDE.md "docs/**/*.md"

Expected Behavior: Prettier passes, and every link in the AGENTS.md table resolves. The pre-commit and pre-push hooks (lint-staged, type-check, knip, test, build) passed.

🔗 Related Issues

None.

✅ Checklist

• Code follows project coding standards
• Self-review completed (plus a separate fresh-context review; its 6 findings are fixed)
• Tests added/updated and passing (no code changes; suite passes in pre-push)
• Documentation updated (if needed)
• No new warnings introduced
• Commit messages follow conventional commits

📝 Notes

• .claude/ Markdown was not Prettier-clean before this branch. It is now, but CI still only checks docs/**, so these files can drift again.
• Worth a reviewer's eye: the new layer-direction line in AGENTS.md, and security.md now loading only for src/**/*.ts (the invariants themselves always load through AGENTS.md).