docs: compact CLAUDE.md by offloading restated detail (#151) #152

Merged

james merged 1 commit from 151-compact-claudemd into main 2026-06-19 22:19:05 +00:00

Conversation 2 Commits 1 Files changed 1 +33 -67

james commented 2026-06-19 22:16:11 +00:00

Owner

Copy link

Closes #151.

Summary

CLAUDE.md had grown to 199 lines, several of which restated detail
that already lives canonically in linked ADRs or docs/ci.md. Because
Claude reads CLAUDE.md on every turn, every restated paragraph is paid
for in context budget — and is a second source of truth that can drift.

This PR compacts each restated passage to "rule + pointer" form. Every
detail dropped is one click away in its canonical source; no information
is lost.

Section	Action
Auth public-routes enumeration	Rule only; the list lives in lib/auth/public-routes.ts
Themes DS token list	Rule + ADR-0023 pointer
Test coverage thresholds	Rule + ADR-0019 pointer
Package-age mechanics	Rule + ADR-0022 pointer
SHA-pin YAML example	One-sentence rule
Install scripts mechanics	Rule + docs/ci.md pointer
Release pipeline minutiae	Trigger + signing + pointers
Conventional Commits type list	Format + enforcement + pointer

199 → 165 lines (~17%).

Test plan

• CI green (this is docs-only; no test impact expected)
• Reading the file end-to-end, every hard rule, stack default,
  orientation pointer, and out-of-scope item is still present
• Every compacted section links to its canonical source

Closes #151. ## Summary `CLAUDE.md` had grown to 199 lines, several of which restated detail that already lives canonically in linked ADRs or `docs/ci.md`. Because Claude reads `CLAUDE.md` on every turn, every restated paragraph is paid for in context budget — and is a second source of truth that can drift. This PR compacts each restated passage to "rule + pointer" form. Every detail dropped is one click away in its canonical source; no information is lost. | Section | Action | | --- | --- | | Auth public-routes enumeration | Rule only; the list lives in `lib/auth/public-routes.ts` | | Themes DS token list | Rule + ADR-0023 pointer | | Test coverage thresholds | Rule + ADR-0019 pointer | | Package-age mechanics | Rule + ADR-0022 pointer | | SHA-pin YAML example | One-sentence rule | | Install scripts mechanics | Rule + `docs/ci.md` pointer | | Release pipeline minutiae | Trigger + signing + pointers | | Conventional Commits type list | Format + enforcement + pointer | 199 → 165 lines (~17%). ## Test plan - [ ] CI green (this is docs-only; no test impact expected) - [ ] Reading the file end-to-end, every hard rule, stack default, orientation pointer, and out-of-scope item is still present - [ ] Every compacted section links to its canonical source

james added 1 commit 2026-06-19 22:16:11 +00:00

docs: compact CLAUDE.md by offloading restated detail (#151) ... e741d1e7d0

Several passages in CLAUDE.md restated detail that already lives
canonically in linked ADRs or docs/ci.md. Because CLAUDE.md loads on
every Claude turn, every restated paragraph is paid for in context
budget — and is a second source of truth that can drift.

Compact to "rule + pointer" form:
- Auth public-routes enumeration → rule only; list lives in code
- Themes DS token list → rule + ADR-0023 pointer
- Test coverage thresholds → rule + ADR-0019 pointer
- Package-age mechanics → rule + ADR-0022 pointer
- SHA-pin YAML example → one-sentence rule
- Install scripts mechanics → rule + docs/ci.md pointer
- Release pipeline minutiae → trigger + signing + pointers
- Conventional Commits type list → format + enforcement + pointer

199 → 165 lines; no information lost, every dropped detail is one
click away in its canonical source.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

forgejo-actions commented 2026-06-19 22:17:00 +00:00

Copy link

Trivy (container image)

Threshold: high  ·  Total findings: 121  ·  At/above threshold: 1

critical	high	medium	low
0	1	50	70

severity	id	package	installed / range	fix
high	CVE-2026-12151	undici	6.25.0	6.27.0, 7.28.0, 8.5.0

<!-- scanner-comment: trivy --> ### Trivy (container image) **Threshold:** `high` &nbsp;·&nbsp; **Total findings:** 121 &nbsp;·&nbsp; **At/above threshold:** 1 | critical | high | medium | low | |---:|---:|---:|---:| | 0 | 1 | 50 | 70 | | severity | id | package | installed / range | fix | |---|---|---|---|---| | high | [CVE-2026-12151](https://avd.aquasec.com/nvd/cve-2026-12151) | undici | 6.25.0 | `6.27.0, 7.28.0, 8.5.0` |

forgejo-actions commented 2026-06-19 22:18:28 +00:00

Copy link

📊 Test coverage

Patch coverage: no testable lines changed.

Overall (app/, lib/, db/, excluding UI per ADR-0019):

Metric	Value	Soft target
Lines	86.6% ✅	≥ 50%
Branches	81.0% ✅	≥ 75%
Functions	90.8%	informational

Soft thresholds per ADR-0019. Coverage is informational and does not block merge.

<!-- coverage-comment --> ## 📊 Test coverage **Patch coverage:** no testable lines changed. **Overall** (`app/`, `lib/`, `db/`, excluding UI per ADR-0019): | Metric | Value | Soft target | |---|---|---| | Lines | 86.6% ✅ | ≥ 50% | | Branches | 81.0% ✅ | ≥ 75% | | Functions | 90.8% | informational | Soft thresholds per [ADR-0019](docs/adr/0019-coverage-soft-targets.md). Coverage is informational and does not block merge.

james merged commit f1d1919ea8 into main 2026-06-19 22:19:05 +00:00

james deleted branch 151-compact-claudemd 2026-06-19 22:19:05 +00:00

james referenced this pull request from a commit 2026-06-19 22:19:06 +00:00

Merge pull request 'docs: compact CLAUDE.md by offloading restated detail (#151)' (#152) from 151-compact-claudemd into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area:auth

Authentication and authorization

  

area:ci

Forgejo Actions, build, test, security, release

  

area:db

Database abstraction, migrations, persistence

  

area:infra

Containerization, deployment, foundational tooling

  

area:native

React Native app (Android + Linux Flatpak)

  

area:pwa

PWA / web frontend

  

area:service

Backend service, API routes, persistence

  

epic

High-level tracker; links several feature tickets

  

feature

A user-facing feature

  

foundation

Foundational work that other tickets build on

No labels

area:auth

area:ci

area:db

area:infra

area:native

area:pwa

area:service

epic

feature

foundation

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

james/carol!152

No description provided.