diagram

diagram — 機械で正確に描画し、モデルに図をでっち上げさせない

中心となる原則は、archify から借りたもので、正しいためそのまま維持します。モデルは描画しません。 モデルはスキーマ付きの宣言書にロジックを記入するだけです（どのブロックがあり、ブロック A とブロック B がどうつながるか）。 描画は決定論的なコードが行います。描画後、機械が自動でレイアウトを検査します。問題があれば、以前の正常な版を保持し、問題箇所を明確に伝えます。決して粗悪な図を出力しません。

それが、モデルに SVG を直接描かせずにこのスキルを使う理由でもあります。誤った図でも「それらしく」見えてしまうため、レイアウトの問題は最も見逃されやすいエラーの一種です。

WHAT

目的とコンテキスト

• 目的： 決定論的なコードで図（関係／フロー）とグラフ（数値データ）を描画します。モデルはスキーマ付きの宣言書に記入するだけで、機械が描画してレイアウトを検査します。問題があれば、以前の正常な版を保持し、問題箇所を明確に伝えます。
• トリガー（使用する場面）： ユーザーが「図を描いて」「グラフを描いて」「フローを描いて」「アーキテクチャ図」「処理フロー」「flow」「graph」「chart」「可視化」「2つのフローを比較」「draw a diagram」「sequence diagram」「state machine」「dependency graph」「plot」「dashboard」「convert Mermaid」「diff two flows」と言った場合（完全な一覧は description にあります）。
• 対象外： UI／ランディングページの画面には使用しません。それは hallmark の役割です。新しい図の SVG 座標を手作業で指定しません。自動生成されるドキュメント内の図のジェネレーターを置き換えません。

メンタルモデル

閲覧者の質問 → 数値軸があるか？ → 図（文法 → archify）またはグラフ（dataviz + 5つの lieflat ルール）→ HTML ファイル → 標準ゲート（frontend-antipattern、任意で visual-receipt）→ アトミックな受け渡し（新しい版が合格なら置き換え、不合格なら以前の版を保持）。モデルがロジックを記入し、コードが描画し、決定論的なゲートが合否を判定します。

入力と出力の契約

	フィールド	必須？	意味
入力	フロー／関係または数値データの説明	はい	閲覧者が答えを知りたい質問
入力	図の種類	いいえ	architecture、workflow、sequence、dataflow、lifecycle。空欄の場合はエンジンが推定します
入力	既存の Mermaid	いいえ	貼り付けると、archify が描き直します
入力	実際のコードへのアンカー	いいえ	sources[] + meta.repository + --repo-root（SHA は40文字ちょうど）
出力	自己完結型 HTML ファイル	はい	図またはグラフ。標準ゲートを通過します
出力	ゲートの判定	はい	frontend-antipattern.py の rc（0 は問題なし、1 は FAIL、2 は WARN のみ）。任意で visual-receipt.py（0 は合格、1 は不合格、2 はスキップ）+ 4枚の画像 + JSON のレシート + コンタクトシート

ルールと機能

• RULE-01 (MUST)：モデルは描画しません。 モデルは宣言書に記入し、コードが描画します。新しい図の SVG 座標を手作業で入力していることに気づいたら、すでに誤った分岐に進んでいます。
• RULE-02 (MUST)：粗悪な図を出力しません。 新しい版がゲートに合格しなければ、以前の正常な版を保持し、問題箇所を明確に伝えます。このリポジトリのジェネレーターはすでにそのように動作します（build-overstack-docs.py の _deliver：一時ファイルにレンダリングし、そのファイルに対してゲートを実行し、合格した場合にのみ os.replace を実行します）。
• RULE-03 (MUST)：スキップ ≠ 問題なし。 Chrome、ネットワーク、エンジンがない場合は「スキップ」と伝え、決して「合格」と報告しません。嘘をつくゲートが合格を示すのは、ゲートが存在しないよりも悪いことです。
• RULE-04 (MUST)：外部エンジンのスタイル制約を、標準ルールとして持ち込まないでください。 まず測定します。archify は矢印を水平または垂直にするよう求めますが、このリポジトリの図には意図的な放射状配置があります（3つの図で、6・4・10本の斜線はすべて有効です）。そのため、そのルールは取り込み時に除外し、残りの3つの幾何学的ルールは採用します。
• RULE-05 (MUST)：自動生成されるドキュメント内の図にはジェネレーターを使い、エージェントを呼び出さないでください。 チャット経由で図を描くたびにエージェントの実行が1回必要で、そのコストは恒久的に発生します。一方、コードで SVG を生成すればコストは0です。チャットの分岐は、新しい図や一度だけ使う図に限って使用します。
• 機能：決定論的な図の描画エンジンとグラフエンジンを呼び出すこと、HTML ファイルに対して0トークンの静的ゲートを実行すること、任意で実際のブラウザーを実行してキャプチャとリクエストの測定を行うこと、アトミックな受け渡しによって出力先ファイルを記録すること。

失敗時の境界

• 数値軸があるかどうか不明 → 確認（「私が描くものに数値軸はありますか？」と尋ねます）。
• 要求が製品画面 → ブロックし、hallmark に引き継ぎます。
• 図表が規律に違反（軸の切断、データマークへのグロー／3-D、データが少なすぎる） → 理由を示して拒否／格下げし、誠実な代替案を提示します。
• deliver が赤、またはゲートが FAIL → 失敗。出力先ファイルは引き続き古い良好な版のままです。誤りの箇所を報告します。
• Chrome／ネットワーク／エンジンが不足 → スキップし、「合格」とは決して報告しません（RULE-03）。
• コードアンカーが不正（SHA が 40 文字未満、origin が一致しない） → ブロック（フェイルクローズ）。

方法

メインワークフロー

ステップ	種類	入力	アクション	出力／終了	失敗時／次の処理
W01	判定	要求	分岐を選択：数値軸あり → 図表、なし → 図、画面 → hallmark	分岐	UI → ブロック、不明瞭 → 確認
W02	判定	閲覧者の質問	図：文法（トポロジー、シーケンス、プロセス、状態、階層、マトリクス）を選択。一つの質問につき一つの図	archify type	質問が二つ → 図を二つ
W03	効果	宣言	図：自然言語または node ~/.agents/skills/archify/bin/archify.mjs（B01）で archify を呼び出します	HTML ファイル	rc 1 → 失敗。古い版を維持
W04	効果	データ	図表：最初のコード行より前に dataviz を読み込み、5 つの lieflat ルールを適用します（B02）	HTML ファイル	規律違反 → 拒否／格下げ
W05	決定論的	HTML ファイル	ホームゲート python3 fdk/tools/frontend-antipattern.py <file.html>	rc 0	1 → 宣言を修正し、W03／W04 を繰り返す
W06	決定論的	HTML ファイル	任意のブラウザー証拠 python3 fdk/tools/visual-receipt.py <file.html>（B03）	画像＋レシート	2 → スキップと報告し、合格とは報告しない
W07	効果	ゲート通過済みファイル	アトミックに引き渡し：新しい版が緑なら出力先ファイルを置き換え、赤なら古い良好な版を維持し、誤りの箇所を報告します	出力先ファイル	—

各ステップの詳細（W01～W07 の信頼できる情報源）：

何かを始める前に分岐を選ぶ

何を表現していますか	分岐	エンジン
コンポーネント間の関係／フロー／順序（ボックス＋矢印）	図	archify
数値データ — 比較、分布、傾向、構成比	図表	dataviz ＋以下の lieflat 規律
製品画面	ここで扱う作業ではありません	hallmark

不明ですか？ 次のように尋ねます。「私が描くものに数値軸はありますか？」 ある → 図表。ない → 図。

図の分岐では、エンジンを選ぶ前に適切な文法を選ぶ

まず尋ねます。閲覧者はどんな質問に答えられる必要がありますか？ — 質問が文法を決め、文法が図の形を決めます（plannotator/effective-html の HÒA TAN を参照。[[design-foundation]]）。

閲覧者の質問	文法	archify type の例
何があり、何とつながっていますか？	トポロジー／システム図	architecture
時間の経過とともに何が起きますか？	シーケンス／タイムライン	sequence
意思決定／変換はどのように行われますか？	プロセスフロー	workflow
これはどのように状態が変化しますか？	状態図	lifecycle
何が何を含む／所有していますか？	階層／包含	architecture（入れ子の分岐）
選択肢同士をどのように比較しますか？	マトリクス／行をそろえた比較	表。archify は不要
どれくらい／どのくらいの頻度で／どれくらい速くですか？	定量的な図表	→ 下の図表分岐

一つの図に二つの質問を詰め込まないでください。両方が必要なら、二つの図（またはオン・オフを切り替えられるレイヤー）にします。過積載の一つの図にはしません。文法を選んでから、下の項目に従ってエンジン（HTML/CSS、SVG、Canvas、WebGL）を選びます。

図解ブランチ — archify 経由

外部エンジンであり、[[adapt-modes]] に従って外部から取り込みます。こちらで書き直すことはせず、ピン留めして呼び出すだけです。 インストール：npx skills add Rheinmir/archify -g -s archify（実際のインストール先は ~/.agents/skills/archify です）。 これは tt-a1i/archify のフォークです。5つ目のプリセット macos（liquid glass + Roboto）を追加し、 デフォルトに設定しています。meta.visual_preset を省略すれば、追加の手順なしでそのまま標準テーマになります。 パッチ適用済みの macos-roboto ブランチがフォークのデフォルトブランチなので、ref をピン留めする必要はありません。

代償を払って学んだ2つの落とし穴があります。同じ間違いを繰り返さないでください。

• --ref フラグはありません。 また、owner/repo@ブランチ でもインストール時にブランチをピン留めできません。CLI は Source: …git @macos-roboto と表示しますが、実際にはデフォルトブランチをインストールし、@ の後ろを スキル名として解釈して No matching skills found と報告します。これが、構文ではなくデフォルトブランチで ピン留めする理由です。
• -l は実際のインストールの代わりになりません。 add … -l は緑色で Found 1 skill と表示しますが、実際のインストールコマンドは 依然として失敗します。インストール経路を確認するには、実際にインストールしてから図を描画し、 data-preset の値を確認してください。

Upstream に新しいバージョンが出たら、ブランチを rebase してください。tt-a1i/archify で上書きインストールしないでください。

チャットで自然言語を使って呼び出します — コマンドプレフィックスはありません：

Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.

種類を明示すれば推測せずに済みます — architecture · workflow · sequence · dataflow · lifecycle。既存の Mermaid を貼り付けても、きれいに描き直してくれます。

実際に実行して確認した、呼び出す前に知っておくべき3つのこと：

1. パッケージには "private": true が設定されており、npm には公開されていません。npx archify は実行できません。シェルからのコマンドはすべて node ~/.agents/skills/archify/bin/archify.mjs … です。
2. 終了コードは一般的な 0/1 の規約に従いません。2 は使い方のエラー（不明なコマンド、不明なフラグ、 不明な図の種類）と「Chrome がないため visual-check をスキップ」の両方に使われます。実際の validate/render/deliver の失敗は 1 です。CI で呼び出す場合は、意図的に分岐させてください。
3. 赤い deliver の後は、出力ファイルを確認しないでください — そこにあるのは、今回失敗したものではなく、以前の正常なバージョンです。 これはアトミックな配信の直接的な結果であり、バグではありません。

lifecycle には、スキーマではなくコードに埋め込まれた3つのルールがあります — 2026/09/10 に計測し、 フォークで修正済みのため、新しくインストールしたバージョンでのみ適用されます：

• レーン名は契約です。 main → 上段、terminal → 下段（Outcomes）、それ以外のすべての ID は中央の段にまとめられます。 別の名前（outcome、recover など）にすると中央の段に配置され、重なります — これはレイアウト調整に4ラウンドを費やした原因です。
• 必要な高さは2種類あります。 terminal レーンを使わない場合 → viewBox[1] ≥ 510、使う場合 → ≥ 630。パッチ適用前はどちらも 566 と報告されていたため、566 で terminal を宣言すると、抜け出せない 「State exceeds the vertical lifecycle area」のループに陥りました。
• メインレールは自動的にリレーションになりません。 step の順序は線を描くだけです。Route Probe / passport / trace で認識させるには、実際の transition を宣言する必要があります（間隔が狭ければラベルは省略します）。 ノードをクリックして Semantic Passport を読み、No connected relationships と表示されたら、validate/visual-check が緑でも図の中身は空です。

実際のコードに沿ったアーキテクチャ図を作るには、sources[]（パス + 行範囲）+ meta.repository

• --repo-root を指定してください。このゲートはフェイルクローズです。revision は40文字ちょうどの SHA である必要があり、--repo-root は origin が一致するトップレベルのチェックアウトでなければなりません。アンカーが間違っている場合は、描画を拒否します。

グラフの分岐 — dataviz + lieflat-charts の規律

すべての環境で、グラフのコードを最初の1行書く前に dataviz スキルを読み込んでください（HTML、 SVG、matplotlib/plotly/d3/Recharts、レンダリングする PNG 画像など）。さらに、 lieflat-charts から取り入れた5つのルールを加えてください。すべて見た目より優先されます。

1. 拒否は正しい対応であり、頑固さではありません。 軸の切断（broken axis）→ 拒否し、誠実な方法を3つ提示します。データマークへのグロー／グラスモーフィズム／3D表現 → 拒否します。色を求めるカテゴリが6つを超える場合 → モノクロの色階調に戻します。選んだ図に対してデータが少なすぎる場合（例：ノードが3つしかないのにフォースグラフを求める）→ より単純な図に切り替え、その理由を説明します。
2. 図の数 = 独立した結論の数であり、データ列の数ではありません。質問1つ → 図1つ、記事全体 → 4〜6つ、1ページにつき最大6つまでとし、それ以上はページを分けます。
3. タイトルは結論であり、図の種類の名前ではありません。「4月のリリース後に解約率が2倍に増加」であり、「解約率の棒グラフ」ではありません。
4. 図を選んだ根拠を示してください。 描画する前に、少なくとも3つの候補を挙げ、それぞれを却下した理由を説明します。「棒グラフを使います」とだけ述べ、却下した候補がない場合、選定したとはいえません。
5. レンダリングは決定的であること。 グラフでの Math.random() の使用は禁止です。2回更新しても同じ図が表示されなければなりません。ファイル全体で1つのカラーパレットを使います。異なる2つのパレットを混ぜた場合は、やり直しです。

HTMLファイル作成後 — リポジトリのゲートを実行

外部エンジンはレイアウトをチェックします。以下のゲートは、エンジンが把握できない、このリポジトリの規約をチェックします。

python3 fdk/tools/frontend-antipattern.py <file.html>     # 0 sạch · 1 FAIL · 2 chỉ WARN

次の項目を決定的に検出し、トークンを消費しません。

• 幾何学 — 2つのボックスの一部が重なる、ボックスが viewBox の外にある、テキストが親ボックスからはみ出す。
• アクセシビリティ + 自己完結性 — role="img" がない、<title> がない、または <title> が最初の子要素ではない、<title>／<desc> が空、リモートの http 参照がある（自己完結型のページをオフラインで開くと画像が欠落します）。
• 証拠へのアンカー — data-src="path"／data-src="path:line" を宣言したノードについて、パスが解決できない、または行番号がファイルの行数を超えている。フェイルクローズです。宣言がなければチェックされませんが、宣言した場合は正しくなければなりません。

実際のブラウザーでの証拠が必要な場合（静的解析だけでは不十分です）：

python3 fdk/tools/visual-receipt.py <file.html>           # 0 pass · 1 fail · 2 BỎ QUA

4枚の画像（1440×900 と 2048×1320、それぞれライトとダーク）、JSON のレシート1つ、人が採点するためのコンタクトシートを生成します。正規表現では検出できない次の3項目を、実際のブラウザーでチェックします。横方向のはみ出し、コンソールエラー、外部へのすべてのリクエスト。つまり、自己完結性をファイル内の文字列ではなく、実際の動作で測定します。

分岐

ID	種類	条件	動作	スキップ／失敗	再合流
B01	conditional_required	数値軸がない（関係、フロー、順序）	archify を使った図解分岐（外部で実行、Rheinmir/archify を fork）	archify が未インストール → npx skills add Rheinmir/archify -g -s archify でインストールします。Chrome がないため終了コード 2 → スキップし、未達として扱います	W05
B02	conditional_required	数値軸がある	dataviz + lieflat の5つのルールを使ったグラフ分岐	要求がルールに違反する → 拒否し、誠実な方法を3つ提示します	W05
B03	capability_optional	実際のブラウザーでの証拠が必要で、Chrome がある	visual-receipt.py：画像4枚、JSON のレシート、採点用コンタクトシート	Chrome がない → rc 2 でスキップ	W07
B04	user_optional	アーキテクチャ図を実際のコードに基づかせる	sources[] + meta.repository + --repo-root を宣言します	アンカーが不正 → エンジンが描画を拒否します（フェイルクローズ）	W03
B05	conditional_required	図が自動生成ドキュメントに含まれる	リポジトリのジェネレーター（例：build-overstack-docs.py）を使い、エージェントを呼び出しません	新規または使い捨ての図 → チャット分岐	W05

検証と停止条件

決定的なチェック：frontend-antipattern.py の rc（幾何学、アクセシビリティ + 自己完結性、data-src アンカー）と、visual-receipt.py の rc（横方向のはみ出し、コンソールエラー、外部へのリクエスト）です。archify では、rc 1 は実際の失敗です。rc 2 は使い方のエラーであると同時に visual-check のスキップを意味するため、意図的に別の分岐へ進む必要があります。人による確認が必要な項目：visual-receipt のコンタクトシート。lifecycle では、ノードをクリックして Semantic Passport を読みます。ゲートが緑でも No connected relationships と表示される場合は、中身がありません。ゲートが緑で、対象ファイルが更新されていれば停止します。赤の場合は以前のファイルを保持して報告します。

例

• Positive: 「Browser -> API -> Redis cache -> PostgreSQL fallback のフローを描く」→ 軸は切り詰めない → 図、トポロジー文法 → Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback. → frontend-antipattern.py rc 0 → macos プリセットの HTML ファイルを納品。
• Boundary/failure: 「売上グラフを描き、軸を切って急増しているように見せる」→ グラフ分岐、broken axis は拒否（lieflat ルール 1）、誠実な方法を 3 つ提示。タイトルは結論とし、「売上棒グラフ」にはしない。
• Boundary: lifecycle で lane を outcome に設定 → 中央の帯が重なる → terminal に変更し、viewBox[1] ≥ 630 にする。deliver がまだ赤なら、対象ファイルは以前の良好な版なので、新しい版として調べない。

起源

• 図の分岐：Rheinmir/archify @ macos-roboto（外部から取り込み — tt-a1i/archify のフォーク。 エンジンは外部で稼働し、こちらではピン留めして呼び出す）。sources/draft/080926-archify-fork-pin.md を参照。
• グラフの規律：larashero3-dotcom/lieflat-charts（統合 — ルールのみを取り込み、描画一式は取り込まない）。
• 幾何学チェックとアトミックな納品：archify から fdk/tools/frontend-antipattern.py および fdk/tools/build-overstack-docs.py に取り込み。wiki/sources/draft/040926-absorb-round.md を参照。