ロードマップ

次に何を作るか、そして——より確信をもって——何を作らないか。以下の各項目は機能の願望リストではなくエビデンス記録に照らして正当化されている。その記録は、最も自明に見える次の機能に対してこそ容赦がないからである。

現在地

6 つの測定が記録されている。まとめて読むと 3 つのことを述べ、4 つ目を含意する。

クレームストアは 2 回測定され、2 回とも null だった。 Q1 と W2 はいずれも 2 群 6 エージェントで実施し、12 人中 12 人が罠を回避した。ストアを指示された群のほうが到達までのツール呼び出しは多かった。Q1b では 13 件中 11 件のクレームが、読み手がどのみち出会うものを言い換えているだけだと判明した。クレームの散文を上手にすることは、次の改善点ではない。

精査に耐えた機構はアンカーである。 M1 はそれが機能することを示し（偽陽性 0.61%、後に 0.00% へ）、Q1c はその死角を正確に描いた（18 件中 7 件はアンカーが動かないまま破れる。リポジトリ全体が従う規則には、結び付けるべきシンボルが存在しないため）。測定可能な強みと測定可能な限界の両方を持つ機構こそ、その上に積む価値がある。

旧来の陳腐化レポートは税だった。 W1 では実ドリフト 3 件すべてが再スタンプで処理され、コードもクレームも変わらず、防げた回帰はゼロ、さらに 18 件中 0 件しかコミットのメタデータだけでは判定できなかった。これが本プロジェクト史上最も重大な変更を生んだ。forge drift はクレームが引用する evidence テストを実行するようになり、bugfix ワークフローは落ちる再現テストを、そのバグが生むクレームの evidence: にする。

そして含意——本ロードマップがこの形をしている理由：これまでの測定はすべてクレームストアを検証してきた。 変更ライフサイクル（spec・tasks・ゲート・verify・アーカイブ）はコードベースのより大きな部分でありながら、エビデンスが一切ない。仕様を先に書くと手戻りが減るのか、誰も問うていない。

フェーズ 0 — 使うこと。作るのをやめること。

以下のすべてはこの項目に従属する。

Forge は 0.1.0 に達し、ドキュメント・インストーラ・3 つのホストを備える。実プロジェクト 1 つには W3 で引き渡した適合テストが既に入っており、導入は半ばまで進んでいる。本プロジェクトが一度も持たなかったものは、自分自身の仕事で継続的に使う一人の利用者 である。エビデンスページの数字はすべて n=3〜6 であり、借り物のリポジトリ上でエージェントが生成し、課題を設計した当人が採点したものだ。

実プロジェクト 1 つに、実変更 10 件のあいだ Forge を適用する。 凝った計装は不要。使い、邪魔になった箇所を書き留める。その摩擦ログが以降すべての入力になる。

警戒すべき失敗様式は、このハーネスが防ぐために存在するものが自らに向いた姿——誰も読まない成果物を生む儀式である。2 行の修正にトラック C が馬鹿げて感じられるなら、それは規律の問題ではなくデータである。

R1 — `forge stats`

これは Q1 の最初の分析にあった選択肢 C そのものであり、当時「成果物が既に存在するのでほぼ無償」と評されながら、一度も作られていない。フェーズ 0 の前では無価値、直後では有価値なので、両者は同時に出す。

報告すべきもの（すべて verification.json・change ディレクトリ・ドリフト台帳から導出可能）：手戻り率、最初に緑になるまでの verify 失敗回数、change new から archive までの経過時間、ドリフト事象とその評決（V1〜V4 対 confirm）、変更ごとのクレーム追加・引退・置換、そして強制率（テストやガードを挙げている pitfall / invariant クレームの割合）。

報告してはならないもの：クレーム数、「知識カバレッジ %」、その他「誰かがクレームをもう 1 つ書くと上がる」指標すべて。Q1・Q1b・W2 はいずれも同じ方向を指している。散文を増やすことは目的ではなく、それを報いる指標は必ず最適化されてしまう。

R2 — ストアではなくライフサイクルを測る

ストアは 2 回測って 2 回 null だった。3 回目は誠実な次の一手ではない。未検証のまま残っている大部分を測ることがそれである。

問い：実装前に仕様を書くことは結果を変えるのか、それとも単なる間接費か。

形：フェーズ 0 の実作業による対比較。同等の変更を、半分は spec と tasks を伴うトラック B/C で、半分はトラック A で通し、手戻り率・レビュー指摘・緑までの時間を比較する。

従来どおりの規律は交渉の余地なく適用される。最初の change を開く前に、採点基準と null 条件をコミットで確定すること。 データを見た後に基準を選んだ測定は、測定ではない。

Q1 より綺麗に走らせるのが難しいことは織り込んでおく。変更は対応づいた組にはならず、実施者は自分がどちらの群かを知っているからだ。それは計画に明記する。事前に述べた限界は、事後に弁護する数字より価値がある。

R3 — クレームストアを任意にする

残された中で最も安価かつ決定的な実験である。

2 度のエージェント実験はストアの有効性を示せなかった。3 度目も同じだろう。しかし ストア無しで実変更 10 件を回し、欠けていると感じるかを見ることは、どのエージェント試験にもできない形で問いに答える。欠けを感じた本人が、何のために必要だったかを正確に言えるからだ。

これは導入障壁も誠実に取り除く。現状、新しいリポジトリは何の利益を見る前にストアを bootstrap せねばならず、その利益こそ未実証のものである。アンカー・変更ライフサイクル・ドリフト・ verify は populated なストアに依存しない。ツールが依存するふりをすべきではない。

ストアが欠けていると分かれば、それこそ 2 度の実験が生み出せなかった肯定的結果であり、しかも「何のために」の具体的説明を伴って現れる。

R4 — 強制率がストアの真の KPI

Q1c の結論は、価値があるのは散文ではなく evidence:——そのクレームを強制するもの——だということだった。bugfix ワークフローは既にそれを構造として強制している。バグは落ちる再現テストを生み、そのテストがクレームの evidence になる。

したがってフェーズ 0 を通じて測れる問いは単純である：強制率は上がるか。 本リポジトリで最初に測ったとき、forge check は 5 件中 4 件が強制手段を挙げていないと報告した。実変更 10 件がストアを「実際に強制されているものの目録」へ動かすなら、ストアは散文にできない仕事を見つけたことになる。率が動かないなら、R3 の答えははるかに容易になる。

実使用からの追加（2026-09-17）

R1〜R4 は測定から論じた。以下の 4 項目は、本プロジェクトがこれまで持たなかったもの ——自分の仕事でそれを使い、どこが痛いかを述べる一人の利用者——から論じている。本ロードマップの最終節は「まさにそれによって改訂される」と述べており、これらは規律の例外ではなく、規律が機能した最初の実例である。

並びは問題の痛みの強さではなく、費用と成功見込みの比による。R5 は R3 の順序も動かす。理由は R5 に記す。

R5 — 次のセッションを拘束する知識

実使用から。 あるセッションで合意した規則が次のセッションでは消えている。ひとつの機能に限定したはずの修正が後続機能に影響するのに、それを記録する場所がない。

なぜ Q1 と W2 では決着していないか。 両者が測ったのは同じこと——既に十分に自己文書化されたリポジトリで、整理された知識へのポインタが単一エージェントの罠回避を助けるか。2 回とも null。セッション N の決定がセッション N+1 を拘束するかは、どちらも測っていない。 Q1b はその次元をリーチ（作業場所から遠い所に記録された知識）と名付けたが、検証されていない。さらに、会話で合意した規則には重複すべき文書が存在しない。これこそ Q1b が「ストアが所有すべき唯一の種類」と結論づけた知識である。

機構は 2 つ、いずれも既存のものを再利用する。

締めの一手。 change をアーカイブする際に「どこにも書かれていない合意は何か」を問う。 Forge に archive はあるが、この問いを立てる瞬間がない。
記録の判定は計算可能であり、主観ではない。 forge impact は既に diff と波及範囲を分離している。波及範囲が diff を大きく超える修正、または共有モジュールに届く修正はクレーム候補であり、波及範囲が diff と一致する修正は局所的で記録すべきでない。「修正がどこに影響するかを見る」という直観の機械化である。

制約。 CON-・PIT-・ADR を再利用する。新しいクレーム種別は追加しない——「クレーム種別の追加」は下の「作らないもの」に挙げてあり、本項目がその最初の例外になってはならない。

何をもって失敗とするか（いま宣言する）。 実変更 10 件を通じて、この方法で記録されたクレームが後続セッションから一度も引用されない、あるいは決着済みの同じ問いが以前と同じ頻度で蒸し返されるなら、機構は失敗であり、誠実な対応は削除である。測定代理指標はセッションあたりの「再議された決定の件数」。

順序に関する注記——本項目は R3 を動かす。 R3 はストア無しで運用し、欠けを感じるかを見る提案である。その実験を R5 より先に走らせると、ストアは無意味な理由で「欠けていない」となる——そもそもこの仕事を与えられていなかったからだ。R5 が先でなければ、R3 の null は何も答えない。

R6 — 新規プロジェクトの受け入れを厳しくする

実使用と診断から。 ある実プロジェクトは、成熟した既存製品のマニュアルと「これと同じようなものを作れ」という要求から始まった。返ってきたものには画面フローがなく、ボタンはあるが何も起きず、本番のように見える UI の裏にダミーデータがあり、機能は最も字義どおりの解釈で実装されていた ——SQL エディタはテキスト領域だけで、構文強調も行番号も検索置換も整形もない。参照製品にはすべて備わっており、提供されたマニュアルに記載されていた。

この失敗には明確な形がある：エージェントは語句を満たす最小限を実装し、語句が含意する製品を実装しない。 参照資料がある場合はより悪い。情報が手元にありながら使われなかったからだ。

3 つの追加。

製品意図を、誕生時に一度だけ。 docs/system/product.md：この製品が存在する理由、対象利用者、参照する製品、そして実際に効く部分——非目標と先送りリスト。OVERVIEW.md は システムを記述するが、意図を記述するものがない。「あの製品のような」が一度もスコープに変換されなかった理由がこれである。
タスクの前にフロー成果物。 要件はシナリオを持つが、画面間の移動を強制するものがない ——まさに欠けていたものである。
参照パリティ。 参照製品が与えられた場合、各機能の仕様は参照製品ができることを列挙し、各項目は実装するか、理由付きで明示的に先送りするかのいずれかとする。SQL エディタならその一覧は構文強調・行番号・検索置換・整形・補完である。沈黙こそが欠陥である。

同じ事案から小さな規則が 2 つ導かれる。対話可能なコントロールは要件へ追跡できるか、さもなくば 存在してはならない。本番に見える UI の裏にダミーデータを出荷することは、様式上の注意ではなくゲート不合格である。

安全装置——追加 3 点より重要。 出力は明示的な先送りリストであって、実装の義務ではない。「黙って省いてはならない」は「すべて作らねばならない」ではない。これが無ければ新規プロジェクトはすべて儀式と化し——フェーズ 0 が警告する失敗様式——ハーネスは 3 週間でアンインストールされる。

何をもって失敗とするか。 成果物は書かれるのに同じ欠落が出荷され続けるなら——パリティ一覧が埋まっているのに何ひとつ選ばれない、あるいは先送りリストがすべてを先送りするなら——受け入れは単なる押印である。第二の兆候：新規プロジェクトの受け入れが最初に動く増分より長くかかるなら、儀式が勝っている。

いまは作らないもの： BRD・SRS・FRS を独立した文書として生成すること。いずれもケイパビリティ仕様を言い換えたものになり、2 つの出典が乖離することこそ、このハーネスが検出するために存在する失敗である。監査や顧客のために SRS が必要になったら、仕様の横に書くのではなく仕様から エクスポートすべきであり、しかも実在の人間が求めたときに限る。

R7 — `ui` 検証条件

実使用から。 崩れるレイアウト、幅が狭いと消えるコントロール、縮小で切れるテーブルの文字、テキスト・ラベル・タグへの場当たり的な配色。これらがレビューを通過する理由は記録されている： 型検査もリントもビルドも通るのに、レイアウトは壊れる。 別種の欠陥であり、別の検査が要る。

機構、そしてアーキテクチャは変えない。 CONDITIONS と commands: に ui を追加する。 Forge は何もレンダリングせず依存も増やさない——プロジェクト自身の Playwright と axe のスイートを実行して結果を記録する。tests と同じである。意見ではなくエビデンス。

公開されている実践から、そのスイートが表明すべきこと：

宣言したビューポート群で水平オーバーフローが無いこと。祖先に overflow-x が無い場合のみ違反として数える
対話可能なコントロールがすべてのブレークポイントで到達可能であること
色はトークンのみ——コンポーネント内に生の hex を書かない
WCAG AA コントラスト。これは感覚ではなく計算される
タッチ標的 44px、切り詰めは偶然ではなく宣言によること

既定ではなく記録された決定でなければならないもの。 正しいレスポンシブ・テーブルは存在しない。比較に使うテーブルは行と列を保ち、先頭列を固定して水平スクロールさせるべきであり、一覧に使うテーブルは積み重ねるほうがよい。そして display による積み重ねはスクリーンリーダーが依拠するテーブル本来のセマンティクスを破壊する。どちらもトレードオフなので、その選択はコンポーネントライブラリの既定ではなく仕様に属する。

何をもって失敗とするか。 誰もスイートを用意せず ui がどのプロジェクトでも unavailable を返すなら、その条件は芝居であり撤去すべきである。第二の兆候：スイートを持つプロジェクトで実変更 10 件を経ても一度も fail にならないなら、表明が弱すぎるか、問題がそもそも無かったか ——どちらも知る価値がある。

R8 — 平均を禁じ、何も指定しない

実使用から。 フロントエンドに「AI が作った感じ」が出る。原因はモデルの能力不足ではなく、 制約のない入力に対する統計的平均化である。モデルは最も確からしい設計を予測し、最も確からしい設計とは見てきたすべての平均である。2026 年の兆候は名指しできるほど具体的だ：紫から青へのグラデーション、既定書体としての Inter、グリッドに 4 枚のカード、そしてすべてに同一の角丸と余白——ページが平坦に読める理由である。

機構：様式ではなく否定リスト。 既定であるがゆえに禁じられる既定を列挙したスキルを持ち、代替は何も指定しない。平均を禁じれば選択が必要になり、選択には理由が要る。エージェントが発明してよい範囲を狭めない唯一の形式がこれである。

助言であり、ゲートには決してしない。 Forge は自らの機構を測定し、失敗した箇所も公開してきた。美的な権威は獲得していないし、それを主張すればエビデンスページと矛盾する。失敗様式を止めるのは R7 であり、R8 は論じるだけである。

模倣ではなく読む価値のあるデザインシステム（いずれもトークン・コンポーネント・利用指針を寛容なライセンスで公開）：データ密度の高いもの——データベースクライアントの形——にはまず Primer（GitHub）、次いで Carbon、Spectrum、Material 3、Cloudscape。

何をもって失敗とするか——ここが微妙である。 禁止リストが新しい制服になれば——誰もが紫を避けて同じ緑を出荷するなら——ひとつの平均を別の平均に置き換えただけであり、原則があるように見えるぶん悪化している。リストは禁色を列挙するのではなく既定の種類を禁じるべきであり、追加によって保守するのではなく実際の出力と突き合わせて読み直すべきである。

抱えているリスク

差し迫っているからではなく、既知だから挙げる。

pre-commit フックが evidence テストを実行するようになった。 forge drift --staged --test は対象ごとに 30 秒のタイムアウトで、キャッシュなしに実行する。大規模リポジトリでは、複数のクレームに触れるステージ済み変更がコミットを遅くし、人が --no-verify に手を伸ばす——それがフックの消滅の仕方である。緩和策はコストの低い順に、コミット SHA によるキャッシュ、本当に陳腐化したクレームのみの実行、対象ごとではなく全体予算の適用。

テストスイートは Windows で約 12〜15 分かかる。 コストはライフサイクルテストでの git サブプロセス呼び出し（1 件 2〜4.5 秒）であり、新しい evidence 実行（1 件約 0.4 秒）が原因ではない。これは仮定され、その後測定され、仮定のほうが誤っていた。欠陥ではなく貢献者の摩擦であり、直す価値が出たときの手当てはテストごとではなく共有フィクスチャリポジトリである。

利用者 1 名、OS 1 種、実際に動かされた言語 1 つ。 C# には文法と宣言表が入ったが、C# のリポジトリはまだ 1 つも bootstrap されていない。機能は現実に当たっておらず、最初の実 C# プロジェクトが何かを見つけるだろう。

意図的に作らないもの

いずれも妥当に聞こえるが、エビデンスが反対している。

2 人目の実利用者が現れる前のホスト追加。 3 つは実証された需要を既に上回る。
リポジトリ横断の知識ストア。 未解決質問で P2 に保留済み。単一リポジトリの知識すら有効と示されていない段階で、共有知識は同じ賭けの拡大版にすぎない。
クレーム種別の追加や、より豊かな散文。 Q1・Q1b・W2 はいずれも逆を指す。ストアの問題は表現力不足ではない。
誰かがクレームを 1 つ書くと上がる指標。 意図して 2 度書いている。

このロードマップの改訂方法

フェーズ 0 の摩擦ログと、データが溜まった後の forge stats によって改訂する。ハーネスが「備えているべきもの」を推論することによってではない。エビデンスページの 6 件中 3 件は設計に反する結果であり、そのいずれもが設計を変えた。本プロジェクトで確実に機能してきた機構はそれだけである。