docs: BFA を root boundary / Feature boundary / Sub-boundary の3層で再定義する

[mk3008]

Summary

BFA の説明を boundary.ts 中心ではなく、
root boundary, Feature boundary, Sub-boundary
の3層モデルとして再整理したい。

本件の目的は、boundary.ts の命名規約を説明すること自体ではない。
BFA における "boundary" の意味を repo 全体で一貫させ、
ルート構成と feature 内部構造を同じ理論で説明できるようにすることが目的である。

Background

現在の rawsql-ts では、app code roots は以下の3つで整理されている。

• src/features
• src/adapters
• src/libraries

また、feature-first layout を前提とし、
feature ごとに SQL や QuerySpec を所有する方針がある。

一方で、BFA の説明では

• ルート境界の話
• feature 境界の話
• boundary.ts の命名規約の話

が同じレベルで混ざりやすく、
"boundary とは何か" が docs 上でやや曖昧になっている。

Problem

現状の説明のままだと、以下の問題が起きやすい。

• ルート境界 と Feature境界 が別思想に見える
• boundary.ts が BFA の本質であるかのように読める
• feature 内の単なる整理フォルダと Sub境界の違いが曖昧
• db, tests/support, .ztd まで同じ種類の "境界" に見えやすい
• VSA と BFA の関係が読み取りにくい

Proposal

1. boundary の親定義を明記する

boundary とは、所有者、責務、許可依存、公開面、検証単位を説明できる
ソース上のまとまりと定義する。

2. BFA を3層で定義する

Root boundary

app code を最初に分類する最上位境界とする。

rawsql-ts における root boundary は以下の3つだけとする。

• src/features
• src/adapters
• src/libraries

Feature boundary

src/features/<feature-name>/ に置かれる、
ユースケース所有の境界とする。

Feature boundary は、その feature が持つ SQL, QuerySpec,
orchestration, feature-local verification を所有する。

Sub-boundary

Feature boundary の内部で、必要なときにだけ切る任意の境界とする。

Sub-boundary は、少なくとも以下のいずれかが変わるときに成立する。

• responsibility
• allowed dependencies
• public surface
• verification scope

上記が変わらないフォルダは、Sub-boundary ではなく
単なる整理フォルダとする。

3. 境界として数えない repo 領域を明記する

以下は重要な repo 領域だが、BFA の root boundary には含めない。

• db
• tests/support
• .ztd

これらは boundary model の主役ではなく、
repo 運用上の特別領域として扱う。

4. VSA の位置づけを整理する

VSA は BFA と競合する別思想ではなく、
Feature boundary の内部で境界を再帰的に運用するためのローカルルールとする。

5. boundary.ts の位置づけを下げて正しく置く

boundary.ts は、Feature boundary または Sub-boundary で使う
既定の scaffold 規約として扱う。

ただし、

• BFA の本質そのものではない
• repo 全域での必須ファイル名ではない
• 単に discoverability と scaffold 運用のための既定である

ことを明記する。

Why It Matters

• BFA の主語が "命名規約" ではなく "境界モデル" になる
• ルート構成と feature 内部構造を一つの理論で説明できる
• VSA と BFA の関係が明確になる
• 単なる整理フォルダと Sub境界を区別しやすくなる
• human と AI の両方にとって、repo の読み方が安定する

Acceptance Criteria

• docs に boundary の親定義がある
• docs に Root boundary, Feature boundary, Sub-boundary の定義がある
• root boundary が src/features, src/adapters, src/libraries の3つだけだと明記される
• db, tests/support, .ztd は root boundary に含めないことが明記される
• VSA が Feature boundary 内部の運用ルールとして説明される
• boundary.ts は scaffold convention であり、BFA の本質ではないと明記される
• 単なる整理フォルダと Sub-boundary の違いが例付きで説明される

Non-goals

• 既存ディレクトリの全面 rename
• boundary.ts の全面廃止
• boundary.ts の repo-wide 強制
• db, tests/support, .ztd を root boundary に昇格させること