diff --git a/docs/journal/2026-05-23.md b/docs/journal/2026-05-23.md new file mode 100644 index 0000000..d4593d4 --- /dev/null +++ b/docs/journal/2026-05-23.md @@ -0,0 +1,115 @@ +# 日報 2026-05-23 + +> セッション継続のため、作業範囲は **2026-05-22 後半 〜 2026-05-23** に跨る。`Date:` ヘッダは記録日 = 2026-05-23。 + +## 作業範囲 + +NeNe フレームワーク改修。FT13 (前セッションから継続) 〜 FT17 の 5 trial + 評価レポート (#401) 由来 7 件 + cross-repo handoff 1 件を完走。 + +## 完了タスク + +### Field Trial (5 件) + +| FT | テーマ | 採用 ADR | Trial Issue | Report | +| --- | --- | --- | --- | --- | +| FT13 | email-sending | **ADR-0006** Symfony Mailer | #374 | #375 | +| FT14 | security-headers | **ADR-0007** ResponseDecoration boundary | #383 | #384 | +| FT15 | request-id | (ADR-0007 generality 実証) | #389 | #390 | +| FT16 | agent-bearer-auth | **ADR-0008** Optional Bearer | #380 (cross-repo) | #396 | +| FT17 | schema-diff CLI | **ADR-0009** schema migrations | #417 | #418 | + +### 評価レポート (#401) 由来 7 件 + +別 Claude による peer review (`REPORT_project_evaluation.md` 88/100、`REPORT_commercial_feasibility.md`) を保管し、指摘事項を 7 PR で完全消化: + +- **#404** ADR README index 0003-0008 追加 → PR #410 +- **#403** CI 強化 (Phan + format:check + checkout v4 + Docker buildx cache) → PR #411 +- **#406** "debug" controller dead-code 削除 (2020 年初版以来の 6 年放置を git log で確認) → PR #412 +- **#405** 型 tightening (`$REQUEST_JSON` parameterize + `ApiResponse::failure` array-shape) → PR #413 +- **#408** Security tightening (`Request::getFile` defense-in-depth + 新 `RedirectGuard` fail-closed allowlist) → PR #414 +- **#407** test 補強 (TransactionManager nested + DataModelBase fixture-based、+15 cases) → PR #415 +- **#409** ADR-0009 schema migration story draft → PR #416 → **FT17 で実装まで完遂** + +### Merged PR (24 件) + +FT13: #375 / #379 / #381 / #382 +FT14: #384 / #387 / #388 +FT15: #390 / #393 / #394 +FT16: #396 / #399 / #400 / #402 (#395 final HTTP smoke) +評価レポート対応: #401 (report 保管) / #410 / #411 / #412 / #413 / #414 / #415 / #416 +FT17: #418 / #422 / #423 / #424 + +## 数値変化 + +- **ADR**: 5 本 → **9 本** (0006 / 0007 / 0008 / 0009 採用) +- **Unit tests**: 89 → **142** (+53, +60%) +- **CI strictness**: Phan + format:check が PR ごとに走るように (baseline drift 検知有効化) +- **CI 速度**: runtime-smoke 2m28s → 1m11s (Docker buildx + gha cache、~50% 短縮) +- **REPORT_commercial_feasibility.md 最大懸念** (migration 機構欠如): **解消** (operator-applied `composer schema:diff`) + +## 構造的に重要だったもの + +### **ADR-0007 が長年の宿題を消した** + +FT7 (#311) で documented した「decoration trap at dispatcher boundary」を FT14 で `ResponseDecorator` + `HttpEmitter::emit()` + `View::execute()` の **2 hook 設計**で正面解決。FT15 で同 boundary が observability (request-id) でも動くことを **validation trial として実証**。これで future の cross-cutting concern (Server-Timing / OTel / 監査 fingerprint) は同 recipe で plug-in 可能。 + +### **cross-repo trial governance が確立** + +FT16 で nene-mcp #380 を新 Issue 切らずに直接 trial Issue 化する pattern を実証 → `docs/field-trials/README.md` に **"Cross-repo Issue reuse" subsection** として正式項目化。今後 NENE2 / nene2-python からの handoff も同様運用。Phase 6 thesis (cross-project governance) の最も clean な実装事例。 + +### **評価レポート由来 7 issue を 1 セッションで全消化** + +外部視点 → Issue → PR → merge のループが 1 セッションで一周。`composer check` が定義されてたのに CI で呼ばれてなかった、`actions/checkout@v6` が存在しないバージョンだった等、外部視点でなければ気付けなかった問題が複数 surface。 + +## 技術的な学び (memory 化済) + +1. **PHP の `getenv($k) ?: 'default'` は `'0'` / `''` を falsy 扱いで壊れる** (FT15 F-1) + `$raw = getenv(...); $value = $raw === false ? 'default' : (string)$raw;` が正解。`coding-standards.md` に予防 note 追加。FT16 / FT17 では再発防止できた。 + +2. **Apache mod_php が `$_SERVER['HTTP_AUTHORIZATION']` を strip する** (FT16 F-1) + `apache_request_headers()` / `getallheaders()` まで降りる 4-layer fallback が必要。`agent-bearer-auth.md` に recipe 化。1 時間 hammer 中の最も重い debug。 + +3. **NeNe TODO REST に `GET /todo/item/id_{id}` が無かった** (FT16 F-2) + 姉妹リポの catalog が assumption していた read-by-id 穴。`itemGetRest` 追加で解消。実 user 視点が無ければ気付けなかった。 + +4. **UNIQUE constraint 由来 index が STATISTICS 経由で false-positive warning** (FT17 F-5) + 同 PR 内で `NON_UNIQUE = 1` (MySQL) / `unique = 0` (SQLite) フィルタで解消。SchemaDefinition の `unique` キーは CREATE TABLE 一括管理なので diff path から外す方針が確立。 + +## ハマったところ + +- FT16 の Apache mod_php 問題で T-1 acceptance が 401 になり、debug に約 30 分。`$_SERVER['HTTP_AUTHORIZATION']` 単独に頼ってはいけないことが framework knowledge として固まったので投資対効果はプラス。 +- FT15 で `getenv() ?:` の罠を 1 度踏んだが unit test が即 catch、5 分で fix。test-first 設計が効いた瞬間。 + +## Trial の性格分化 + +FT12 までの「real-app entity 立ち上げ」一辺倒だったのが、本セッションで **5 種の異なる trial 性格** に分化: + +| trial | 性格 | +| --- | --- | +| FT13 | 完全空白 surface 立ち上げ + dep ADR | +| FT14 | structural pattern の正面解決 (長期宿題) | +| FT15 | 前 ADR の generality validation | +| FT16 | cross-repo handoff の handler trial | +| FT17 | 前 ADR の implementation trial | + +trial methodology が成熟してきている。 + +## 翌日以降の候補 + +| Priority | 候補 | 規模 | +| --- | --- | --- | +| Real-app gap | session-storage-backend (Redis) | 中〜大 (ADR-class) | +| Defer chunk | DataMapperBase の PDO 依存 unit test 補強 (#407 残り) | 中 | +| Meta | ai-agent-journey (Phase 6 thesis 自己検証) | 長尺 | +| Observability | structured-logs (JSON formatter swap) | 小 | +| Architecture | constraint-changes ADR (FK / UNIQUE 追加 ALTER 経路) | ADR-class、需要次第 | + +## 雑感 + +評価レポート (#401) が来たタイミングと、ADR-0007 → ADR-0008 → ADR-0009 が連鎖した流れが噛み合って、これまで個別だった structural debt が 1 セッションで複数 closed された。特に **FT7 F-6 が 7 trial 越しに resolved** された瞬間は trial methodology が effective に働いている強い証拠。 + +明日以降は real-app gap (Redis session 等) か meta trial (ai-agent-journey) のどちらかで、また性格を変えたい。 + +--- + +**Status (セッション終了時)**: main green、未 merged ブランチなし、全 trial / 全 issue close 済み。 diff --git a/docs/journal/README.md b/docs/journal/README.md new file mode 100644 index 0000000..158eeda --- /dev/null +++ b/docs/journal/README.md @@ -0,0 +1,31 @@ +# Journal + +Day-by-day session summaries — what was worked on, what merged, what got learned, what's queued for next time. Different from: + +- `docs/field-trials/` — trial-specific reports, scoped to one FT each. +- `docs/todo/current.md` — current state of the work, kept fresh; loses history when items move out of "Active". +- `docs/roadmap.md` — phase-level direction, slow-moving. +- `docs/releases.md` — versioned release notes for users of the framework. + +The journal is the **working log** for maintainers and reviewing AI agents. It captures the texture of a session (what was hard, what surprised, what was deferred) that a list-of-merged-PRs would lose. + +## File naming + +`docs/journal/YYYY-MM-DD.md`, one file per session-day. If multiple sessions happen on the same date, append the file in place rather than creating a sibling. + +## What belongs here + +- Work completed (with PR / Issue references) +- ADRs accepted / drafted +- Notable bugs surfaced + fixed +- Technical traps documented (so future selves don't re-discover them) +- Cross-repo handoffs +- What's queued for the next session + +## What does **not** belong here + +- Code recipes — those go in `docs/development/`. +- Design decisions — those become ADRs. +- Active TODO — that lives in `docs/todo/current.md`. + +A journal entry should be useful 6 months later as "what was the context when this PR was merged?" not as a substitute for the actual artifacts.