docs: slim CLAUDE.md by relocating rationale to internal docs

[The01Geek]

What

Slims CLAUDE.md by removing justification, evidence, history and derivation prose while keeping every operative rule. Two commits on top of each other:

1. Relocation pass — moved substantive rationale for the fattest bullets into docs/internal/claude-md-relocated-rationale.md (+8 sections), keeping instruction + one consequence inline. Also adds a strong preamble directive telling agents to use docs/internal/ as the primary reference.
2. Justification strip — removed the remaining justification/evidence/history sentences across all sections.

Numbers

• CLAUDE.md: 111,764 → 86,348 bytes (−22.7%).
• 124 → 124 top-level bullets — no rule dropped.

Honest framing (corrected after review)

This is not "byte-for-byte unchanged; only rationale removed." Operative instructions are preserved, but many bullets were condensed to instruction + one consequence, and the DevFlow review correctly caught two operative directives that were over-stripped — the no-known-flake "fix the assertion, do not re-run the suite hoping for green" remedy and the --with-floors completion-gate anchor-resolution clause. Both have been restored in this update.

Why not 40%

Removing prose floors at ~82% — the file is mostly load-bearing rules (paths, flags, contracts, constraints), not justification, so there is ~26 KB of prose to remove, not ~60 KB. Reaching 40% would require relocating the rules themselves into docs/internal/, a deliberate reliability trade not taken here.

Verification

• monolith shard: 10,196 passed / 0 failed; all 5 run.sh-pinned CLAUDE.md literals intact and unique.
• lint-brand-devflow-sweep clean — the coupled brand-devflow-buckets.json edit (removing the orphaned green \DevFlow` runs` entry) is correct and required.
• lint-internal-docs: 0 new violations; relocated rationale faithful; all doc pointers resolve.

🤖 Generated with Claude Code

[prflow-implementer]

/prflow:review

[github-actions]

PRFlow Review — PR #2126

Status: ❌ REJECT
Diff profile: engine_self_modifying + config_only → full checklist (CLAUDE.md matches Arm 3)
Run: View run
Reviewed HEAD: e41ea4a
Last updated: Phase 4 (verdict)
Stale-prose lint: disabled by config (prflow_review.stale_prose.enabled=false)

Blueprint

• Classify diff (Phase 0.5)
• Generate verification checklist (Phase 1) — 6 items
• Verify checklist (Phase 2) — 3 passed, 2 failed (VC-1, VC-6), VC-4 checklist-wording artifact (no PR defect)
• Review agents (Phase 3) — 5 agents returned; final-pass extension loaded-empty
• Aggregate & verdict (Phase 4)
• Run complete — everything this run owed

Findings (live)

• [Important → capped Suggestion] --with-floors completion-gate anchor resolution deleted, not relocated (CLAUDE.md, ~line 43). Corroborated by 3 agents (code-reviewer, comment-analyzer, requesting-code-review). The base clause resolving how the --with-floors artifact-regeneration row's "completion-gate whole-suite pass" maps on the local tier was dropped. Materiality low: the surviving "Batch every owed fix" bullet still states the local-tier gate is the CI reading, so the generic rule covers the case. kind: documented_falsehood/documentation_gap.
• [Suggestion] No-known-flake bullet dropped an operative directive (CLAUDE.md, ~line 66). Corroborated by 3 agents. Base "fix the assertion, do not re-run the suite hoping for green" (+ "worse than leaving it open") removed and not relocated; surviving heading "every FAIL is a real failure to diagnose" preserves the core. kind: other.
• [Suggestion] PR description byte figures are inaccurate (PR body, not committed content). Stated −6.2% / 104,822 bytes; actual HEAD CLAUDE.md is 85,982 bytes = −23.1% (verified via git show). The "surviving instructions unchanged byte-for-byte; only rationale removed" invariant is overstated over a 23% cut — a few operative clauses were trimmed too. Informational: does not affect the shipped tree. kind: documented_falsehood.
• [Suggestion] "which still forbid a loop to cite CI for its own progress" dropped in two places (CLAUDE.md, ~lines 43, 209). Single-agent (comment-analyzer), low confidence — the governing rule survives in the extensions; reads as rationale.
• [Suggestion] Trimmed bullets do not link to the relocated rationale doc (CLAUDE.md). Single-agent (silent-failure-hunter). Per the repo's Audit CLAUDE.md and the live prompt extensions together under one placement rule: nothing belongs in both #1352 discipline this is intentional (a link would re-invite verbosity).
• No Critical/Important defects in committed content. Brand-bucket removal is correct and required (the sweep's reverse stale-check would RED otherwise — verified by silent-failure-hunter and pr-test-analyzer against lint-brand-devflow-sweep.py). All 5 run.sh-pinned CLAUDE.md literals survive (final-pass verified). Relocated rationale is faithful (VC-2 PASS). All doc pointers resolve (VC-5 PASS).

Verdict: REJECT — the PR's stated safety invariant is false; two operative directives were dropped from CLAUDE.md (not just rationale), and the PR description's byte figures are wrong. The remedy is small.

Issue Compliance

Reviewed against issue: none — No related issue found, requirement compliance not checked; scope not-established. Requirement-based checklist items are included in the verification results below.

Verification Checklist Results

3 passed, 2 failed, 0 inconclusive — 0 via lite probe, 6 via agent. (VC-4 is a checklist-wording artifact, not a PR defect — the verifier established the code is correct, property_proven: true; it is excluded from the pass/fail counts above and would normalize to PASS.)

• VC-1: FAIL — the PR's claim "surviving instructions unchanged (byte-for-byte); only rationale removed" is falsified. Verified operative clauses were dropped, not just rationale (see findings), and HEAD CLAUDE.md is 85,982 bytes vs base 111,764 (−23.1%), not the claimed −6.2% / 104,822. [CLAUDE.md]
• VC-6: FAIL — at least one operative directive was deleted with no surviving restatement: the no-known-flake bullet's "fix the assertion, do not re-run the suite hoping for green" is absent everywhere at HEAD (verified via git show). [CLAUDE.md]

✅ Passed items (3 of 6) — click to expand

• VC-2: relocated rationale in docs/internal/claude-md-relocated-rationale.md faithfully preserves the removed CLAUDE.md rationale (all six sections cross-checked). [docs/internal/claude-md-relocated-rationale.md]
• VC-3: the brand-devflow-buckets.json removal is correctly coupled — the literal "green DevFlow runs" appears zero times in HEAD CLAUDE.md; exactly that bucket entry was removed. [lib/test/brand-devflow-buckets.json]
• VC-5: all doc pointers resolve at HEAD (claude-md-relocated-rationale.md, claude-md-tiered-suite-rationale.md, index.md). [CLAUDE.md]

Code Review Findings

🟡 Suggestion / Minor

1. --with-floors completion-gate anchor resolution deleted, not relocated (CLAUDE.md) — the base clause resolving how the --with-floors artifact-regeneration row's "completion-gate whole-suite pass" maps on the local tier is gone from both CLAUDE.md and the relocation doc. Low materiality: the surviving "Batch every owed fix" bullet still states the local-tier gate is the CI reading, so the generic rule covers the case. (raised by 3/5 agents) [inertness: first-conjunct=held limb-one=held limb-two=held; evidence: no .sh/.py/.yml/workflow reads CLAUDE.md prose for behavior — test-suite pins only assert the prose; CLAUDE.md is repo-local and the vendor slice ships no copy]
2. No-known-flake bullet dropped an operative directive ("fix the assertion, do not re-run the suite hoping for green") (CLAUDE.md) — removed and not relocated; the surviving heading "every FAIL is a real failure to diagnose" preserves the core intent. (raised by 3/5 agents) [inertness: first-conjunct=held limb-one=held limb-two=held; evidence: as above]
3. PR description byte figures are inaccurate (PR body, not committed content) — states −6.2% / 104,822 bytes; actual HEAD is 85,982 bytes = −23.1% (verified via git show). Undermines the PR's own verification evidence and the "only rationale removed" framing over a 23% cut. (raised by 1/5 agents)
4. "which still forbid a loop to cite CI for its own progress" dropped in two places (CLAUDE.md) — governing rule survives in the extensions; reads as rationale. (raised by 1/5 agents)
5. Trimmed bullets do not link to the relocated rationale doc (CLAUDE.md) — per the repo's Audit CLAUDE.md and the live prompt extensions together under one placement rule: nothing belongs in both #1352 discipline this is intentional (a link would re-invite verbosity). (raised by 1/5 agents)

over-grade annotation: findings 1, 2 and 4 are behavior-inert CLAUDE.md prose (both Phase 4.1.5 limbs hold), capped at Suggestion — they drive no REJECT at the critical threshold.
truthfulness sweep: no finding promoted (the findings concern removals, not diff-added false claims).
intra-diff contradiction scan: no contradiction found.

No Critical/Important defects in committed content. The brand-bucket removal is correct and required (the sweep's reverse stale-check in lint-brand-devflow-sweep.py would RED otherwise — verified by two agents). All five run.sh-pinned CLAUDE.md literals survive (final-pass verified). CI reports lib + python tests, lint, and all shards green for this commit.

Verdict Criteria applied

• Rule 1 (any verification-checklist FAIL → REJECT) fires on VC-1 and VC-6, which are genuine non-normalizable FAILs (property_proven: false, inaccuracy_scope: source_authored_text — the PR's own asserted invariant is false, not merely awkward generated wording).
• The Phase-3 code-review findings are all behavior-inert CLAUDE.md prose capped at Suggestion, so they do not independently drive REJECT at the critical threshold; Rule 1 determines the verdict.

What to change before merge (small)

1. Restore or relocate the two dropped operative directives — the no-known-flake "fix the assertion, do not re-run the suite hoping for green" remedy, and the --with-floors anchor-resolution clause (either back in CLAUDE.md or into claude-md-relocated-rationale.md).
2. Correct the PR description's byte figures to the real values (HEAD 85,982 bytes, −23.1%) and describe the change honestly as "operative directives condensed to instruction + one consequence, with a few refinement clauses dropped" rather than "byte-for-byte unchanged; only rationale removed."

Everything else in the relocation is sound: the moved rationale is faithful, the coupled brand-bucket edit is correct and required, and every mechanical pin passes.

[prflow-reviewer]

Verdict: REJECT — full report in PR comment

The complete review report (checklist results, findings, details) is in the
PRFlow Review progress comment on this PR.