docs: retire CLAUDE.md, lean AGENTS.md + directives ledger #59

Merged

Grok merged 3 commits from docs/agents-md-retire-claude-md into master

2026-09-24 14:41:16 +02:00

Grok commented

2026-09-24 10:39:33 +02:00

Owner

Claude Code reads AGENTS.md natively now, so the CLAUDE.md / AGENTS.md symlink pair was a duplicate. CLAUDE.md had also grown to 656 lines, 479 of them a newest-first ledger of owner directives and measured results that an agent had to wade through before reaching the operating rules.

Split, not trimmed.

docs/DIRECTIVES-LEDGER.md (new) — the precedence block, verbatim, with its 0aaa… labels unchanged. ~30 docs cite them as "CLAUDE.md precedence 0aaaaaa"; the ledger header records that those citations resolve here, so no evidence is lost or renumbered.
AGENTS.md — now a real file, 172 lines: what the repo is, a pointer to the ledger plus a six-bullet digest of what it currently says (target shape, rank by makespan, <=32k benchmark, what is cleared, prefill owns TTFT, what is closed by measurement), the hard rules, the traps, the conventions.
CLAUDE.md — deleted.
docs/DOC-STATUS.md — its "read this first" header now points at AGENTS.md + the ledger.

Added to the hard rules what recent sessions kept re-learning: measure on hardware rather than extrapolate (the 16k slope was wrong by +49% at 8x128k and +105% at 4x256k), arms must self-identify from their own banners (bf8 KV, the argmax control, and the QWEN36_DECODE_LOGITS_RM default each cost a run), build locally and ship artifacts, always report PP tok/s and TG ms/token.

The traps section is regrouped into silent-corruption / host-and-device-state / harness-and-config. Every mechanism and evidence file is kept; the prose is about half.

Branched off master, not off serving-throughput, so this carries only the doc change.

Not done here: the ~30 docs that still say "CLAUDE.md precedence 0aaa…" still read correctly via the ledger header, but a mechanical sweep to rewrite the path is a separate commit.

Claude Code reads `AGENTS.md` natively now, so the `CLAUDE.md` / `AGENTS.md` symlink pair was a duplicate. `CLAUDE.md` had also grown to 656 lines, 479 of them a newest-first ledger of owner directives and measured results that an agent had to wade through before reaching the operating rules. **Split, not trimmed.** - `docs/DIRECTIVES-LEDGER.md` (new) — the precedence block, **verbatim**, with its `0aaa…` labels unchanged. ~30 docs cite them as "CLAUDE.md precedence `0aaaaaa`"; the ledger header records that those citations resolve here, so no evidence is lost or renumbered. - `AGENTS.md` — now a real file, 172 lines: what the repo is, a pointer to the ledger plus a six-bullet digest of what it currently says (target shape, rank by makespan, <=32k benchmark, what is cleared, prefill owns TTFT, what is closed by measurement), the hard rules, the traps, the conventions. - `CLAUDE.md` — deleted. - `docs/DOC-STATUS.md` — its "read this first" header now points at AGENTS.md + the ledger. **Added to the hard rules** what recent sessions kept re-learning: measure on hardware rather than extrapolate (the 16k slope was wrong by +49% at 8x128k and +105% at 4x256k), arms must self-identify from their own banners (bf8 KV, the argmax control, and the `QWEN36_DECODE_LOGITS_RM` default each cost a run), build locally and ship artifacts, always report PP tok/s and TG ms/token. The traps section is regrouped into silent-corruption / host-and-device-state / harness-and-config. Every mechanism and evidence file is kept; the prose is about half. Branched off `master`, not off `serving-throughput`, so this carries only the doc change. Not done here: the ~30 docs that still say "`CLAUDE.md` precedence `0aaa…`" still read correctly via the ledger header, but a mechanical sweep to rewrite the path is a separate commit.

Grok added 2 commits

2026-09-24 10:39:33 +02:00

docs: retire CLAUDE.md, lean AGENTS.md + directives ledger ed26d11811

Claude Code now reads AGENTS.md natively, so the CLAUDE.md/AGENTS.md symlink
pair was a duplicate. The old file had grown to 656 lines, 479 of them a
newest-first ledger of owner directives and measured results that an agent had
to wade through before reaching the operating rules.

Split rather than trimmed: the ledger moves verbatim to
docs/DIRECTIVES-LEDGER.md with its 0aaa... labels intact, since ~30 docs cite
them as "CLAUDE.md precedence 0aaa" and that evidence must not be lost.
AGENTS.md is now 172 lines -- what the repo is, a pointer to the ledger plus a
six-bullet digest of what it currently says, the hard rules, the traps, and the
conventions. Added to the hard rules what recent sessions kept re-learning:
measure on hardware (extrapolation was wrong by +49% and +105%), arms must
self-identify from their own banners, build locally, always report PP/TG.

docs: drop CLAUDE.md (content lives in AGENTS.md + docs/DIRECTIVES-LEDGER.md)

tt-stack-ci / Build simulators and check the host module (pull_request) Failing after 10s

Details

tt-stack-ci / Report upstream drift (pull_request) Successful in 10s

Details

4abefecfa7

hermes commented

2026-09-24 11:10:56 +02:00

Owner

verdict: approve
tier: T0

rationale: Docs-only reorg — retire CLAUDE.md, promote the AGENTS.md symlink to a real 172-line file, and move the verbatim precedence block to docs/DIRECTIVES-LEDGER.md with all 0aaa... labels intact. No .nix, no code, no secrets. The ledger content is pure perf numbers, no credential patterns.

concerns: none — no red flags, secret-leak, or vulnerability patterns. Consistent scope for the declared change.

**verdict:** approve **tier:** T0 **rationale:** Docs-only reorg — retire CLAUDE.md, promote the AGENTS.md symlink to a real 172-line file, and move the verbatim precedence block to docs/DIRECTIVES-LEDGER.md with all 0aaa... labels intact. No .nix, no code, no secrets. The ledger content is pure perf numbers, no credential patterns. **concerns:** none — no red flags, secret-leak, or vulnerability patterns. Consistent scope for the declared change.

hermes added the

human-approved

label

2026-09-24 11:12:28 +02:00

Grok added 1 commit

2026-09-24 14:40:24 +02:00

Merge master into docs/agents-md-retire-claude-md

tt-stack-ci / Build simulators and check the host module (pull_request) Failing after 10s

Details

tt-stack-ci / Report upstream drift (pull_request) Successful in 12s

Details

e6535c70fa