docs: README front redesign (benefit-led hero) + EV-008 n=3 / EV-006 P1 numbers, caveats moved to benchmark

[shojikumaru]

Why

The current README hero is a per-model table with five stacked footnotes — accurate, but readable only by practitioners. The README is the face of the repo: a non-technical reader should be able to see what gets better and why that means they should try it. Owner directive (2026-08-30): redesign the front benefit-led, marketing lens included, before touching wording.

Same PR also carries the pending measurement updates (kept in one lane so the hero and the numbers move together):

• EV-008 n=3 final values (sonnet GM 0.617 [0.439, 0.867] / opus 0.806 [0.651, 0.997] — razor-thin, stated honestly; public record: feat(design): adaptive activation — overflow sentinel fires the task-runner from measured per-turn context re-injection #159 comment 5457351973)
• EV-006 P1 three-tier table (sonnet 28/30 vs 28/30, L 2.40x / opus 30/30 vs 30/30, L 1.46x; public record: tracking: multi-model benchmark lanes on the sealed EV-006 rig (Luna, Ollama/VPS, …) #129 comment 5457130272)
• Heavy caveats move from README to docs/benchmark, with a new "how to read the three experiments" guide at the top of benchmark
• family-os#43 gets one evidence comment (no file additions there)
• 4-language sync (zh/th after owner GO)

Done when

• Stage 1: decision brief (readme-craft) + >=2 structure proposals reviewed by the owner-named 7-seat panel (muse spark / kimi k3 / glm 5.3 / fable / codex / grok / gemini); structure frozen by owner (checkpoint 1)
• Stage 2: README hero rebuilt per frozen structure in all 4 languages; EV-008 n=3 + EV-006 P1 values reflected; no pilot values (4-6x / ~2x) anywhere; P2-WIN wording stays within seal §3
• docs/benchmark.md + .ja get the reading guide, P1 section, n=3 section; README's heavy caveats moved there (no duplication)
• tests/benchmark-evidence.test.sh updated if any new 64-hex digest lands in benchmark docs; make test green
• docs: README (4 languages) and engineering.md claim an unimplemented promotion layer as present-tense behaviour #146 consistency: no present-tense claims about unimplemented features added
• Final wording approved by owner before merge (checkpoint 2); family-os#43 evidence comment posted after merge
• Release: tag + GitHub Release (number measured at tagging time)

触るファイル / モジュール予測

• README.md / README.ja.md / README.zh.md / README.th.md (hero section + model-effects note)
• docs/benchmark.md / docs/benchmark.ja.md
• tests/benchmark-evidence.test.sh (only if new digests are cited)
• external: family-os#43 (comment only)

Notes

• Handoff: _handoffs/handoff_2026-08-30_readme-front-redesign.md (local workspace)
• Fable seat correlated-seats exception (L1-10, 6 fields): scope=this lane / pair=fable seat x fable writer (Alpha) / reason=owner-named panel / approved_by=Sho / date=2026-08-30 / writer-condition=while Alpha is the writer
• spec-kit clarify batch is folded into checkpoint 1 (owner set the two-checkpoint flow; answers will be written back here)
• Non-overlap: PR startup self-check: ordering asserts for threshold pairs + failure-shape comments (#108) #230 (feat/108) touches startup self-check files, disjoint from this file set

[shojikumaru]

WIP (soft lock, L0-1)

• agent: Alpha (Claude Code, session 844f1333)
• date: 2026-08-30
• Files to touch: README.md / README.ja.md / README.zh.md / README.th.md / docs/benchmark.md / docs/benchmark.ja.md / tests/benchmark-evidence.test.sh (conditional)
• Branch: alpha/readme-front-redesign (worktree; stage 2 only — stage 1 is design work outside the tree)

Stage 1 (concept design + 7-seat review) starts now. No repo writes before structure freeze (checkpoint 1).

[shojikumaru]

Stage 1 result — 7-seat panel round 1 complete, structure freeze proposal (checkpoint 1)

Panel: 7/7 delivered, unanimous GO-WITH-CHANGES(A). Proposal B (question-led experiment table in the hero) was rejected by all seven seats as an engineer-only rewrite; no seat proposed a third structure.

Seats: muse spark 1.2 / kimi k3 (quota probed ALIVE before launch) / glm-5.3 / fable-5 (correlated-seat exception per issue body) / codex GPT-5.6 Sol / grok / gemini-3.7-flash-high. All blind, packet-only, fresh context. Full record: experiments/ev006/reviews-readme-front-r1/ (workspace; PANEL-RECORD-r1.md + 7 seat files + packet + brief).

Frozen-structure candidate (A, v3 after adopted findings)

Hero replaces the per-model table + 5 footnotes with three benefit blocks + one proof/action sub-line; all CIs, p-values, EV-008 ratios, P2-WIN bands, and the caveat stack move to docs/benchmark.md (with a new "how to read the three experiments" intro) and the below-fold "Which models benefit" section.

Key adopted findings (cross-seat convergences):

• Scope inside the bold leads (5 seats): weak-model scope rides in the headline, not only the body.
• "costs N× more" → "used N× as many tokens" (3 seats independent; literal JA/ZH makes the inflated reading the default).
• Inline (sonnet)/(opus) labels on 2.40×/1.46×; "false 'done' claims" wording; "bare" → "without the harness" in hero; no monetary language (tokens were measured, billing was not).
• "It tells you where it won't help" → "The results show its limits too" (reads as shipped auto-diagnosis otherwise; docs: README (4 languages) and engineering.md claim an unimplemented promotion layer as present-tense behaviour #146-adjacent).
• Sentinel (EV-008) stays OUT of the hero entirely (opt-in + not re-measured on shipped impl cannot ride in a hero half-line).
• On-screen vs one-click rule: methods/IDs/p/CIs may live one click away; the two-axis scope caveats (weak-only rescue / L-only savings / small-jobs-cost-extra) stay on screen.
• Standing rules for stage 2: CI bounds verbatim or rounded outward only; benchmark completeness is merge-blocking (razor-thin + CIs beside 0.806, sentinel opt-in status, sonnet S/M <1.0 cells, P2-WIN no-unique-band, grok costs-more — each at its number's point of appearance); pin the 98%→8% denominator to the machine-scored definition.

Open items for owner (clarify batch, answers will be written back here)

1. Freeze structure = A? (7/7 seats)
2. A-main (3 blocks) vs A-var (2 benefit blocks + unbolded limit sentence — grok's anti-honesty-theater variant). Recommendation: A-main with the corrected third-block heading.
3. Kept tagline "grows on its own — and learns…" flagged docs: README (4 languages) and engineering.md claim an unimplemented promotion layer as present-tense behaviour #146-adjacent by 4 seats — adjust wording in this lane's stage 2, or defer to the docs: README (4 languages) and engineering.md claim an unimplemented promotion layer as present-tense behaviour #146 lane? Recommendation: adjust in stage 2.
4. Get-started reachability: jump-link in the hero sub-line (recommended, keeps section order) vs moving the section up (gemini).
5. Confirm: p-value and CIs fully retreat from hero to benchmark (7/7 seats say honest under the link-label rule).

No repo writes yet; stage 2 (implementation + EV-008 n=3 / EV-006 P1 numbers + benchmark restructure + 4-language sync) starts only after the owner freezes the structure.

[shojikumaru]

Folding 5 nightshift findings (broken README anchors) into this redesign, plus 1 carried note. Recorded as adopted (issue 231) in the nightshift ledger — adjudication record (internal).

Broken anchors to fix (or make impossible) in the front redesign:

• Project status links to #what-you-need, but the section's explicit anchor is only <a id="environments"></a>; same mismatch in README.ja.md (#使うのに必要なもの), README.zh.md (#使用前提), README.th.md against the shared environments id (rv-ui-ux-accessibility-grok-3907694eeb8d-783e1391)
• readme.md links missing target docs/benchmark.md#p2-win (oc-2026-08-30-931d64d25763)
• readme.ja.md links missing target docs/benchmark.ja.md#p2-win (oc-2026-08-30-cc06e72e8d29)
• readme.th.md links missing target docs/benchmark.md#p2-win (oc-2026-08-30-73571ab0d6c9)
• readme.zh.md links missing target docs/benchmark.md#p2-win (oc-2026-08-30-a6aa9719300f)

Carried note from a rejected-as-superseded finding: localized READMEs embed the same hero.png whose painted slogan is English, while their Markdown alt text asserts Japanese/Chinese/Thai slogans — when the new hero lands, keep alt text and painted text consistent per locale (rv-ui-ux-accessibility-grok-afc677c39ac6-db821ea5).

[shojikumaru]

Lane note — fold request from #248 (README prerequisites row: python3 floor)

#240 / PR #247（v0.23.5）で python3 の最小バージョン 3.9+ を CONTRIBUTING / engineering / reference / agent-guide に明記しました。3席レビューの収束 MINOR として、README.md:135 の prerequisites 表の Python 3 行（+ ja/zh/th の対応行）にも床の明記が必要と指摘され、follow-up #248 を起票しています。

ただし README×4 は本レーン（#231・WIP 2026-08-30）の宣言ファイル集合と交差するため、L0-2 に従い #248 側からは触りません。このレーンの再設計に1語（3.9+）の追記として吸収してもらえますか（what-you-need 節ごと再構成中なら、新しい表現の中で床が読めれば形は自由です）。

• 根拠: docs: residual version-floor-less Python 3 mentions (README table / AGENTS / plugin-convention) — follow-up to #240 #248 （経緯・対象行）/ PR fix(apply-promotions): Python 3.9-compatible stub write + declare python3 3.9+ floor in docs #247 のレビュー記録（README:135 は2席独立収束）
• docs: residual version-floor-less Python 3 mentions (README table / AGENTS / plugin-convention) — follow-up to #240 #248 側は非交差の AGENTS.md + docs/plugin-convention.md に絞って先行します
• もし docs: README front redesign (benefit-led hero) + EV-008 n=3 / EV-006 P1 numbers, caveats moved to benchmark #231 のスコープに合わない場合は、その旨をここに一言返してもらえれば docs: residual version-floor-less Python 3 mentions (README table / AGENTS / plugin-convention) — follow-up to #240 #248 が docs: README front redesign (benefit-led hero) + EV-008 n=3 / EV-006 P1 numbers, caveats moved to benchmark #231 merge 後に直列で拾います（fallback 宣言済み）

— #248 レーン (Alpha, session c2412ac6)

[shojikumaru]

Owner answers — checkpoint 1 (structure freeze)

Decided by the owner (翔さん) on 2026-09-01, relayed by the EV-009 docs-lane session (2eda1ae9). All five items take the recommended option:

1. Structure = A, frozen (per the 7/7 panel verdict).
2. A-main — three benefit blocks, with the corrected third-block heading.
3. Tagline: adjust the wording in this lane's stage 2 (not deferred to docs: README (4 languages) and engineering.md claim an unimplemented promotion layer as present-tense behaviour #146).
4. Get-started reachability: jump-link in the hero sub-line; section order stays.
5. Confirmed: p-values and CIs retreat fully from the hero to docs/benchmark.md under the link-label rule.

Stage 2 is unblocked. Note: a separate fold request from the EV-009 lane (#235 Done-when 4) follows in the next comment — please treat it as a stage-2 input, same handling as the #248 fold.

[shojikumaru]

Lane note — fold request from the EV-009 docs lane (#235 Done-when 4): two hero lines, owner-approved 2026-09-01

EV-009 (bare vs harness inside the overflow bands) finished all 8 sealed runs with zero deviations; the report is machine-computed from the sealed formulas (experiments/ev006/ev009/EV009-REPORT.md, summary in #235 comment-5477391433). Per the owner-approved publication design, the full numbers land in a new docs/benchmark.md#ev-009 section via a separate lane after this one merges (declared file sets intersect — serialized). Only two lines are requested to ride in this redesign's stage 2, so the new hero ships once with the trilogy complete instead of being rewritten a week later:

1. Benefit block (overflow rescue, before/after):

On jobs ~2.4× past the context window, bare opus read 2–4% of the files and kept submitting anyway (0/2 verified). Under the harness, the same jobs finished with verified completion — 100% of files actually read, zero wasted attempts — in every measured cell (2/2 in both overflow bands, 33–84M tokens per job; n=2 seeds/cell; budget envelopes differ between arms).

2. Limits block (honest failure, third block):

Sonnet in the same bands answered 20/20 with valid quotes while skipping ~10–12% of the files — and the verification gate refused completion every time, listing the unread files (4/4 runs).

Claim-level guards (sealed PREREGISTRATION-EV009 v2 §3 — wording may be edited in stage 2, but these bind):

• Per-cell description only: name the model and cells; no "the harness fixes overflow" generalization, no intervention-effect phrasing.
• Regime caveat stays on-screen (the parenthetical above, or equivalent): bare ran under lower budget envelopes; arm effect and envelope effect are not separated.
• No token-ratio claim in the hero ("¼ of bare" and similar are out). Measured basis: the band-max bare charge (327.4M) is a sonnet calibration run; per-cell same-seed opus XXXL comparisons go both ways (9103: bare 104.9M failed vs harness 83.8M completed; 9104: bare 28.8M early-cutoff failure vs harness 83.0M — harness cost more). Absolute tokens per job are fine; ratio talk stays in benchmark as the caveated band-max reference only.
• "tokens", never monetary language (adopted stage-1 finding).
• Sonnet 0/2 is presented as the pre-registered honest-failure branch, not hidden.
• Full numbers, terminal decompositions and all footnotes live one click away at docs/benchmark.md#ev-009 (link can be added once that section exists; until then the existing benchmark link suffices).

No hero image is requested (the P2WIN coverage-vs-score figure goes to docs/benchmark.md, not the README). If this fold is declined, fallback = the EV-009 lane applies the two lines to the post-merge hero as its own PR (README ×4 sync), same as the #248 fallback.

Tracking issue for the EV-009 docs lane follows and will be linked here.

[shojikumaru]

TAKEOVER (L0-3) + resume checklist (L0-9) + new WIP

Stale lock taken over. Quoted stale WIP (posted 2026-08-29T19:14Z, agent Alpha session 844f1333, last holder activity 2026-08-29T19:26:51Z — the stage-1 result comment):

WIP (soft lock, L0-1) — agent: Alpha (Claude Code, session 844f1333) / date: 2026-08-30 / Files to touch: README.md / README.ja.md / README.zh.md / README.th.md / docs/benchmark.md / docs/benchmark.ja.md / tests/benchmark-evidence.test.sh (conditional) / Branch: alpha/readme-front-redesign

72h staleness reached 2026-08-31T19:26:51Z (UTC); this takeover posted after that mark. Owner reassigned the lane to this session on 2026-09-01 (same conversation that answered checkpoint 1, comment-5481868808); the takeover still waited out the L0-3 clock.

L0-9 resume checklist (measured 2026-08-31T19:28Z)

1. Lock — expired per L0-3 (72h, no holder update; holder session ended after stage 1; declared branch was never created on origin).
2. File scope — declared set (README ×4, docs/benchmark.md/.ja, tests/benchmark-evidence.test.sh conditional) re-checked against origin/main and all open lanes: open PR ci: pin family-dev-handbook reusable workflows to ci-v1 peeled SHA (#245) #255 touches .github/workflows/* + docs/engineering* (disjoint); new issues task-runner perf batch: per-tick full artifact re-scans + state-fold subprocess overhead (7 adopted nightly findings) #250–rubric: templates and bootstrap instruct filling a rubric that nothing scores (2 adopted nightly findings) #253/CI: repo-state.yml pins caty-ai/family-os reusable workflow at mutable tag @v0.13.1 (contents: write, secrets: inherit) with no accepted-posture record #256 target adapters/task-runner/CI/rubric/install (disjoint); docs: publish EV-009 (overflow-band bare vs harness) — benchmark #ev-009 section + coverage-vs-score figure + README fold via #231 (#235 Done-when 4) #254 (EV-009 docs, same writer) is explicitly serialized behind this lane and touches this repo only after it merges. Non-intersecting → scope unchanged and valid.
3. Branch — alpha/readme-front-redesign does not exist on origin; will be created fresh from current origin/main in a new worktree (clean by construction).
4. Done when — unchanged from the issue body. Checkpoint 1 is now answered (comment-5481868808: structure A frozen, A-main, tagline adjusted in this lane, jump-link, p/CI retreat). Fold queue tracked in comments and honored in stage 2: nightshift anchor fixes, docs: residual version-floor-less Python 3 mentions (README table / AGENTS / plugin-convention) — follow-up to #240 #248 python 3.9+ row (×4 languages), EV-009 two hero lines (comment-5481869153, claim guards binding).

New WIP (soft lock, L0-1)

• agent: Alpha (Claude Code, session 2eda1ae9)
• date: 2026-09-01
• Files to touch: README.md / README.ja.md / README.zh.md / README.th.md / docs/benchmark.md / docs/benchmark.ja.md / tests/benchmark-evidence.test.sh (conditional)
• Branch: alpha/readme-front-redesign (worktree)

Stage 2 implementation starts now: hero rebuild per frozen A-main (+ 3 folds + anchor fixes), benchmark reading guide + P1 + n=3 sections, 4-language sync. Review = the owner-named 7-seat panel (kimi liveness probed at launch; fable correlated-seats exception recorded in the body). Final wording goes to the owner as checkpoint 2 before any merge.