@takagaki/cortex-decisions-viewer 0.12.20 → 0.12.22

package/README.md

@@ -3,7 +3,7 @@
 Cortexの意思決定記録（`Decisions/*.md`）を**静的サイトにビルドして閲覧する**CLIツール。
 各レコードに「**Edit on GitHub**」リンクを付与し、閲覧画面から直接GitHubのエディタで編集できる。
 
-`md-meta-view` の代替として、Cortex専用に自前実装したもの。出力は単一の自己完結HTML（外部依存・サーバー不要）で、AWS Amplify Hosting 等の静的ホスティングにそのまま載る。
+`md-meta-view` の代替として、Cortex専用に自前実装したもの。出力は外部依存もサーバーも要らない静的ファイル一式で、AWS Amplify Hosting や S3 + CloudFront にそのまま載る。**JS と CSS は HTML に埋め込まず、`assets/` の外部ファイルに出す**——配信側（AIS ポータル）の Content-Security-Policy がインラインの `<script>` / `<style>` を実行しないため（[#301](https://github.com/classmethod-internal/cortex-tools/issues/301)）。
 
 ## 使い方
 
@@ -13,7 +13,22 @@ Cortexの意思決定記録（`Decisions/*.md`）を**静的サイトにビル
 npx -y @takagaki/cortex-decisions-viewer build --out site --title "Decisions"
 ```
 
-ビルド結果は `site/index.html`（と `404.html`）。`?id=<id>` で個別レコードに直リンクできる。
+ビルド結果は `site/` ディレクトリ一式。`?id=<id>` で個別レコードに直リンクできる。
+
+| 出力 | 中身 |
+| --- | --- |
+| `index.html` | 画面の骨組みと、埋め込みデータ（`<script type="application/json">`） |
+| `404.html` | `index.html` と同じもの（サブパス直叩きのフォールバック） |
+| `assets/viewer.<内容ハッシュ>.js` / `.css` | 画面のJSとCSS。内容が同じなら名前も同じ（版が同じなら全案件で同じ名前） |
+| `bodies/*.html` | レコードの本文（詳細を開いたときに取りに行く） |
+| `thumbs/*` | グラフのサムネイル画像 |
+
+**配置は `site/` を丸ごと置く**（`index.html` だけを置いても画面は出ない）。
+ファイル名を内容ハッシュにしているのは、`Cache-Control` を付けずに置かれた
+`index.html` をブラウザが発見的にキャッシュするため——固定名だと
+「利用者の手元に残った古い `index.html` が、消えた JS を指す」形になり、
+強制再読み込みまで画面が真っ白になる。中身が変われば URL も変わるなら起きない。
+配置側では `index.html` / `404.html` を `no-cache`、`assets/` を長期キャッシュにするとよい。
 
 ## CLI
 

package/dist/build.js

@@ -1888,7 +1888,26 @@ async function build(opts) {
     // 本文HTML（リッチ・かさばる）を bodies/ へ外出しし、inlineデータからは除外する。
     // 一覧・グラフ・検索は inline の searchText（軽量plaintext）で動き、詳細表示時にbodyRefをfetchする。
     await externalizeBodies(site, outAbs);
-    const html = (0, render_1.renderSite)(site);
+    // CSSとJSは外部ファイルへ出す。**インラインのままだと配信先で画面が出ない**——
+    // AISポータルは /p/<案件>/cm/ に厳格な Content-Security-Policy を返しており、
+    // インラインの style / script を実行しない（cortex-tools #301）。
+    //
+    // ファイル名を内容ハッシュにする理由: 配置先の S3 は Cache-Control を付けずに
+    // 置かれ、ブラウザは Last-Modified からの発見的キャッシュをする。固定名だと
+    // 「利用者の手元に残った古い index.html が、消えた JS を指す」形になり、
+    // 強制再読み込みまで真っ白になる。中身が違えば URL も違うなら、それが起きない。
+    //
+    // 配置側（cortex-engine の build-viewer.yml）の責務: aws s3 sync --delete が
+    // 古いハッシュのファイルを消すこと、index.html に Cache-Control: no-cache を
+    // 付けること（assets/ は内容ハッシュ名なので長期キャッシュでよい）。
+    const assetSources = (0, render_1.viewerAssetSources)();
+    const assets = (0, render_1.viewerAssetNames)(assetSources);
+    await node_fs_1.promises.mkdir(path.join(outAbs, "assets"), { recursive: true });
+    await node_fs_1.promises.writeFile(path.join(outAbs, assets.css), assetSources.css, "utf8");
+    await node_fs_1.promises.writeFile(path.join(outAbs, assets.js), assetSources.js, "utf8");
+    // **renderSite ではなく renderSiteWithAssets を呼ぶ。** 引数を1つ落としても
+    // 型が通ってしまう形にすると、本番の出力が黙ってインラインに戻る
+    const html = (0, render_1.renderSiteWithAssets)(site, assets);
     await node_fs_1.promises.writeFile(path.join(outAbs, "index.html"), html, "utf8");
     // SPA的フォールバック（?id= はクエリなので不要だが、サブパス直叩き対策として404も用意）
     await node_fs_1.promises.writeFile(path.join(outAbs, "404.html"), html, "utf8");

package/dist/render.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UNSETTLED_LIMITS = exports.LIVE_CONFIRM_LIMITS = void 0;
 exports.renderSite = renderSite;
+exports.renderSiteWithAssets = renderSiteWithAssets;
+exports.viewerAssetSources = viewerAssetSources;
+exports.viewerAssetNames = viewerAssetNames;
 exports.sanitizeRegisteredNow = sanitizeRegisteredNow;
 exports.sanitizeHarnessSchedules = sanitizeHarnessSchedules;
 exports.sanitizeHarnessShelf = sanitizeHarnessShelf;
@@ -29,9 +32,19 @@ exports.ingestedAtOf = ingestedAtOf;
 exports.keyMissingText = keyMissingText;
 exports.deriveCapTile = deriveCapTile;
 exports.renderConnectionMap = renderConnectionMap;
+const node_crypto_1 = require("node:crypto");
 const meet_guide_images_1 = require("./meet-guide-images");
-/** SiteDataを単一の自己完結HTML（埋め込みデータ+CSS+JS）にレンダリングする */
-function renderSite(site) {
+/**
+ * SiteDataをHTMLにレンダリングする。
+ *
+ * `assets` を渡すと、CSSとJSを**外部ファイルへの参照**（link/script src）で出す。
+ * 配信側（AISポータル）の Content-Security-Policy がインラインの style / script を
+ * 実行しないため（cortex-tools #301）。本番の出力（build()）は必ずこちら。
+ *
+ * `assets` 省略時は従来どおり単一の自己完結HTML（埋め込みデータ+CSS+JS）を返す。
+ * JSDOM で画面を動かす既存テストがこの形に依存している（外部ファイルは読まれない）。
+ */
+function renderSite(site, assets) {
     // </script> によるブレイクアウトを防ぐため < をエスケープして埋め込む
     // Claude Code Web ディープリンク（この案件リポ＋狙ったプロンプトで開く）。repoBaseUrl から slug を導出（追加入力なし）。
     const repoSlug = site.repoBaseUrl
@@ -54,6 +67,13 @@ function renderSite(site) {
         ? `<a class="gh-btn" href="${escapeHtml(site.repoBaseUrl)}" target="_blank" rel="noopener" title="コンテキストリポジトリをGitHubで開く">${GITHUB_ICON}</a>`
         : "";
     const askBtn = `<a class="ask-ai-btn" href="${escapeHtml(askUrl)}" target="_blank" rel="noopener" title="Claude Code Web でこの案件のリポジトリを開き、プロジェクトについて質問・調査できます">💬 プロジェクトについてAIに聞く</a>`;
+    // CSPでインラインが拒否される環境向けの外部参照形。省略時は従来どおり埋め込む
+    const styleTag = assets
+        ? `<link rel="stylesheet" href="${escapeHtml(assets.css)}" />`
+        : `<style>${CSS}</style>`;
+    const scriptTag = assets
+        ? `<script src="${escapeHtml(assets.js)}"></script>`
+        : `<script>${CLIENT_JS}</script>`;
     return `<!DOCTYPE html>
 <html lang="ja">
 <head>
@@ -61,7 +81,7 @@ function renderSite(site) {
 <meta name="viewport" content="width=device-width, initial-scale=1" />
 <meta name="robots" content="noindex, nofollow" />
 <title>${safeTitle}</title>
-<style>${CSS}</style>
+${styleTag}
 </head>
 <body>
 <header class="site-header">
@@ -77,7 +97,7 @@ function renderSite(site) {
 </footer>
 ${connMap ? `<template id="conn-map">${connMap}</template>\n` : ""}<script type="application/json" id="tutorial-data">${tutorialJson}</script>
 <script type="application/json" id="site-data">${dataJson}</script>
-<script>${CLIENT_JS}</script>
+${scriptTag}
 </body>
 </html>`;
 }
@@ -89,6 +109,31 @@ function escapeHtml(s) {
         .replace(/>/g, "&gt;")
         .replace(/"/g, "&quot;");
 }
+/**
+ * 外部ファイル参照の形でレンダリングする（assets必須）。
+ *
+ * build() はこちらだけを呼ぶ。renderSite は assets を省略できるので、
+ * 本番の出力にインラインが戻る退行を型で止められない。その1点のための薄い関数。
+ */
+function renderSiteWithAssets(site, assets) {
+    return renderSite(site, assets);
+}
+/** 外部ファイルへ書き出す中身。埋め込み形（renderSite の assets 省略時）と同一の文字列 */
+function viewerAssetSources() {
+    return { css: CSS, js: CLIENT_JS };
+}
+/**
+ * 中身から外部ファイル名を決める。
+ *
+ * 内容ハッシュ（sha256の先頭8桁）にするのは、配信先がブラウザのキャッシュを
+ * 持つため。固定名だと「古いHTMLと新しいJS」の組み合わせが起こりうるが、
+ * 中身が変われば名前も変わるなら起こらない。**同じ中身なら同じ名前**なので、
+ * 版が同じかぎり全案件で同じファイル名になる。
+ */
+function viewerAssetNames(sources) {
+    const h = (text) => (0, node_crypto_1.createHash)("sha256").update(text, "utf8").digest("hex").slice(0, 8);
+    return { css: `assets/viewer.${h(sources.css)}.css`, js: `assets/viewer.${h(sources.js)}.js` };
+}
 /** 接続マップの能力定義（表示順・絵文字は詳細カードの流儀を踏襲） */
 /**
  * アダプタのロゴ。**公式配布のSVGをそのまま埋め込む。**
@@ -714,7 +759,7 @@ const STATE_STATUSES = {
     reachable: ["ok", "not_in_channel", "missing_scope", "no_token", "unreachable", "unknown", "not_in_space", "no_credentials"],
     ingested: ["ok", "failed", "skipped"],
 };
-const STATE_ROW_FIELDS = ["cap", "ref", "workspace", "question", "status", "at", "by", "needed", "lastOkAt", "lastFailAt"];
+const STATE_ROW_FIELDS = ["cap", "ref", "workspace", "question", "status", "at", "by", "needed", "detail", "lastOkAt", "lastFailAt"];
 /** stateNow はライブ専用キーで build.ts の網にかからない。画面側でも許可リストを通す */
 function sanitizeStateNow(v) {
     if (!Array.isArray(v))
@@ -775,6 +820,11 @@ function sanitizeStateNow(v) {
  * 書いた行だけスコープ名が消え、「権限が足りません」とだけ出て何を直せばよいか
  * 分からない状態に戻る。上書きするときは空でも必ず載せる——夜間の古い needed が
  * 新しい判定の横に残ると、直したはずのスコープ名がいつまでも出る
+ *
+ * **detail（最後に測った理由）も載せる（#346）。** 夜間が書く理由文はここを通らないと
+ * 画面に届かない（fleet-status.json には焼き込まれないので、ライブが届かない案件では出ない
+ * ——それは意図。古いスナップショットの理由を出すより、出さないほうが嘘にならない）。
+ * needed と同じく、上書きするときは空でも必ず載せる
  */
 function overlayStateOnFleet(view, rows) {
     const v = view || {};
@@ -810,6 +860,7 @@ function overlayStateOnFleet(view, rows) {
             gateAt: hit.at,
             gateBy: hit.by,
             needed: hit.needed || "",
+            detail: hit.detail || "",
         });
     });
     return changed ? Object.assign({}, v, { externalSources: externals }) : v;
@@ -4427,6 +4478,99 @@ ${deriveCapTile.toString()}
       cls: "ds-gate-muted",
     },
   };
+  /**
+   * 休止状態の行に、状態の語に添えて**押す前から**出す定型の補足（#346）。
+   * 鍵は「アダプタ種別（helpTypeOf）× 状態」。値は文のパーツの配列で、文字列はテキスト、
+   * { link: <リンクの文字列> } は GitHub App のインストール設定へのリンク（GITHUB_APP_INSTALL_URL）。
+   *
+   * ## なぜ画面の表で持つのか
+   * サーバの needed / detail は「何が起きているか」と「どこを開くか」までを持つが、
+   * **誰がその操作をできるか**（リポジトリの admin なら自分で・でなければ admin に依頼・
+   * request は組織オーナーの承認待ち）は、夜間（engine）とボタン（Lambda）の2つの書き手が
+   * 別々に文を作るので、サーバ側で足すと片方だけ古くなる。判定と URL はサーバ、定型の補足は
+   * ここ、という役割分担にする。
+   *
+   * 🔴 **DS_GATE には入れない**（実測が返す語彙の表で、突き合わせテストの対象）。
+   * DS_GATE_NO_TOKEN と同じく、仕組みはアダプタ非依存・データだけがアダプタ固有。
+   *
+   * 🔴 **DS_GATE[状態] が help を持つ状態にはエントリを置かない。** 置くと行の補足が2段になる
+   * （github-state-reason.test.mjs の「行の補足は最大1段」が見張る）。
+   *
+   * 🔴 **URL を文字列で書き写さない**（帯・押した結果と同じ定数を使う。写経すると張り替えで
+   * 片方だけ古くなる）。
+   *
+   * エントリがある状態では**この文だけ**を出し、サーバの needed / detail は出さない
+   * ——理由文・補足・確認の一文の3段が issues / discussions の2行 × N リポに並ぶと、
+   * 一覧が案内で埋まる（DS_GATE_NO_TOKEN.github の項と同じ判断）。needed は押した結果が持つ。
+   */
+  var GITHUB_ADMIN_HELP = "このリポジトリの admin（管理者権限を持つ人）であれば、Configure から自分で追加できます（承認は不要です）。"
+    + "admin でない場合は、そのリポジトリの admin の人に「Cortex の GitHub App の対象にこのリポジトリを追加してください」と依頼してください。"
+    + "GitHub 側で request と表示された場合は、組織オーナーの承認待ちです。"
+    + "追加したあと「接続を確認」を押して、読めるようになったことを確かめてください。";
+  var DS_GATE_RESTING_HELP = {
+    github: {
+      unreachable: [
+        "App は導入済みですが、このリポジトリが読み取り対象に選ばれていない（または移動・改名・削除された）可能性があります。",
+        { link: "インストール設定を開く" },
+        " の Configure から対象の組織を選び、Repository access に追加してください。",
+        GITHUB_ADMIN_HELP,
+      ],
+    },
+  };
+  /**
+   * 表を引くときのアダプタ種別。**probeTypeOf を使わない**——あちらは「op=probe の受け口」の
+   * 語彙で、Google Chat に空文字を返す（実測の口が無いため）。ここで使うと Google Chat の
+   * エントリを永久に置けない
+   */
+  function helpTypeOf(type) {
+    var t = String(type || "");
+    return t.indexOf("github") === 0 ? "github" : t;
+  }
+  /** 表のパーツ（無ければ null）。行と押した結果の**両方**がここを通す（写経しない） */
+  function restingHelpPartsOf(type, gate) {
+    var byType = DS_GATE_RESTING_HELP[helpTypeOf(type)];
+    return (byType && byType[gate]) || null;
+  }
+  /** パーツを1段落にする。包む要素の class は置き場所で違う（行は ds-gate-help・押した結果は ds-probe-help） */
+  function restingHelpNode(parts, cls) {
+    var p = el("p", { class: cls });
+    parts.forEach(function (part) {
+      if (typeof part === "string") p.appendChild(document.createTextNode(part));
+      else if (part && part.link) p.appendChild(el("a", { href: GITHUB_APP_INSTALL_URL, target: "_blank", rel: "noopener", text: part.link }));
+    });
+    return p;
+  }
+  /**
+   * 休止状態の行に出す「最後に測った理由」（表にエントリが無い状態のフォールバック）。
+   * needed（次の一手・URL 込み）を優先し、無ければ detail。
+   *
+   * 🔴 **書き手が button の detail は出さない。** ボタンは detail に判定の語そのもの
+   * （"unreachable"）や生のエラー（"ratelimited"）を書く——lastFailDetail を空で潰さない
+   * ための痕跡で、表示用の値ではない（intake の op=probe のコメント）。人向けの文を持つのは
+   * needed の側。夜間（gold）の detail は人向けの文なので出す
+   */
+  function stateReasonOf(s) {
+    if (s.needed) return String(s.needed);
+    if (s.detail && s.gateBy !== "button") return String(s.detail);
+    return "";
+  }
+  /**
+   * この行に、押す前から理由・補足を出してよいか（#346）。**語の列挙で持たない**——
+   * 別の作業が DS_GATE に語や help を足した日に、黙って漏れたり2段になったりしないよう
+   * 導出で決める:
+   *   - 状態がある（未測定の行には出すものが無い）
+   *   - ok でない
+   *   - missing_scope でない（スコープ名の札 .ds-probe-scope が既に持つ）
+   *   - no_token でない（GitHub は組織の帯が導線を1つだけ持つ設計・Slack は DS_GATE_NO_TOKEN の help）
+   *   - not_in_channel でない（help は無いが、**状態の語そのものが操作の指示**
+   *     「Slackで招待してください」。その下に夜間の「読めませんでした: not_in_channel」を
+   *     並べても情報が増えず、招待という具体的な指示を薄める。help の有無とは別の軸）
+   *   - dsGateOf(s).help が無い（あれば DS_GATE の固定文が次の一手を持っている）
+   */
+  function showsRestingReason(s) {
+    if (!s.gate || s.gate === "ok" || s.gate === "missing_scope" || s.gate === "no_token" || s.gate === "not_in_channel") return false;
+    return !dsGateOf(s).help;
+  }
   /**
    * Slack のチャンネルが社内ワークスペースのものか。**workspace の有無だけで決まる**
    * （省略＝社内。#104 でこの値が画面まで届いていることは slack-workspace.test.mjs が見張る）。
@@ -4972,9 +5116,14 @@ ${deriveCapTile.toString()}
     var owners = githubOwnersView();
     var out = [];
     groupGithubByOwner(items, owners).forEach(function (g) {
-      // **行ごとに meta を引く。** issues と discussions でアイコンとラベルが違う
+      // **行ごとに meta を引く。** issues と discussions でアイコンとラベルが違う。
+      // Issues と Discussions は同じ接続先（同じ dev 行）なので、理由・補足は1本目だけが
+      // 持つ（#346）。同じ長文が2行に並ぶと一覧が案内で埋まる
+      var seenRef = {};
       var cards = g.items.map(function (x) {
-        return extSourceCard(x, DS_TYPE[x.type] || { icon: "🔗", label: x.type || "その他" });
+        var again = !!(x.ref && seenRef[x.ref]);
+        if (x.ref) seenRef[x.ref] = 1;
+        return extSourceCard(x, DS_TYPE[x.type] || { icon: "🔗", label: x.type || "その他" }, { quietHelp: again });
       });
       if (g.state === "warn") {
         out.push(orgNoteBox(githubNotConnectedNodes(g), cards));
@@ -5037,10 +5186,18 @@ ${deriveCapTile.toString()}
     var repos = o.repos != null ? o.repos : g.repos != null ? g.repos : g.items.length;
     var unread = o.unreadable != null ? o.unreadable : g.unread != null ? g.unread : g.items.length;
     var installed = o.appInstalled;
-    out.push(el("div", { class: "ds-orgnote-title", text: "⚠️ " + g.title + " はまだ接続されていません" }));
     // **読める件数を出す。** 総数だけ出すと、同じ画面の集計と食い違う（#101 で3度直した形）
     var head = repos + "リポジトリ中 " + unread + "件が読めていません。";
+    // 🔴 **見出しは 「installed」 の分岐の中で出す（#346）。** ここで1つに畳んでいたので、
+    // App 導入済みの組織にも「まだ接続されていません」と出て、**同じ帯の本文と矛盾**した
+    // （実機でオーナーが踏み、利用者が「組織の接続からやり直し」と誤解した）
     if (installed === true) {
+      // **見出しでは「読み取り対象に選ばれていません」と言い切らない。** 下のコメントの
+      // とおり②未選択と③移動・改名・削除は分かれないので、見出しは事実だけを言う
+      out.push(el("div", {
+        class: "ds-orgnote-title",
+        text: "⚠️ " + g.title + " は App 導入済みですが、" + unread + "件のリポジトリを読み取れていません",
+      }));
       // App は入っている。**インストールをもう一度促さないこと**——済んでいる操作を促すのは
       // 「設定する必要が無いものに設定を促す」偽の警告と同じで、しかも直らない
       //
@@ -5049,15 +5206,19 @@ ${deriveCapTile.toString()}
       // 「対象に選ばれていません」と言い切ると、③の人は一覧に無いリポジトリを
       // 探し続けることになる（押しても直らない導線と同じ形）。逃げ道を1文で示す。
       //
-      // **設定画面の宛先も断定しない。** リンク先は 「/settings/installations」＝
-      // **押した本人の**インストール一覧で（appSettingsLink の項に、組織の設定ページが
-      // 管理者以外で 404 になる理由がある）、App を入れたのが別のメンバーや
-      // 顧客側のオーナーなら**着いた先は空**。そこで詰まる人に次の宛先を渡す。
+      // **設定画面の宛先は App 個別ページに統一した（#346）。** 以前の
+      // 「/settings/installations」 は**押した本人が入れた App しか出ない**個人の一覧で、
+      // App を入れたのが別のメンバーなら着いた先が空だった（そのための断り書きも要らなくなった）。
+      // いまの宛先と、そこに着ける人の条件は 「appSettingsLink」 の項にある。
+      //
+      // **誰がその操作をできるかまで書く（2026-09-02 の実測）。** リポジトリの admin なら
+      // Configure から自分で追加でき、admin でなければ GitHub が 「request」 を出して
+      // 組織オーナーの承認待ちになる。片方に断定せず両方の道を並べる
       out.push(el("p", {
         class: "ds-group-note",
-        text: head + "GitHub App はこの組織に入っていますが、これらのリポジトリが読み取りの対象に選ばれていません。"
-          + "インストール設定を開いて、対象のリポジトリを追加してください。"
-          + "設定は App を入れた方の画面に出ます。見当たらない場合は、この組織で App を入れた方にご依頼ください。"
+        text: head + "GitHub App はこの組織に入っていますが、これらのリポジトリが読み取りの対象に選ばれていない（または移動・改名・削除された）可能性があります。"
+          + "「インストール設定を開く」から " + g.title + " の Configure を開き、Repository access に対象のリポジトリを追加してください。"
+          + GITHUB_ADMIN_HELP
           + "リポジトリ自体が一覧に見当たらない場合は、移動・改名・削除されている可能性があるので、登録から外してください。"
           + "お客様の組織では、組織のオーナーに承認を依頼してください。",
       }));
@@ -5065,6 +5226,7 @@ ${deriveCapTile.toString()}
       return out;
     }
     if (installed === false) {
+      out.push(el("div", { class: "ds-orgnote-title", text: "⚠️ " + g.title + " はまだ接続されていません" }));
       out.push(el("p", {
         class: "ds-group-note",
         text: head + "この組織に Cortex の GitHub App を入れると読めるようになります（Issues の読み取りだけ）。"
@@ -5075,7 +5237,13 @@ ${deriveCapTile.toString()}
     }
     // 「null」（確かめられなかった）と、この値を知らない古い fleet-status.json。
     // **導線を出さない。** どちらが原因か分からないので、押させると外れたほうを
-    // 押させることになる（済んでいるインストールをもう一度、あるいは効かない設定画面へ）
+    // 押させることになる（済んでいるインストールをもう一度、あるいは効かない設定画面へ）。
+    //
+    // 見出しは件数を言わない（件数は本文だけが持つ・見出しと二重に言わない）。
+    // 「githubUnsureNodes」 の「接続を確認できませんでした」（＝その夜、確かめる処理自体が
+    // 走らなかった）とは意味が違う——こちらは**読めなかった事実はあるが、App の導入状況が
+    // 分からない**ので、語を分ける
+    out.push(el("div", { class: "ds-orgnote-title", text: "⚠️ " + g.title + " のリポジトリが読めていません（原因は確かめられていません）" }));
     out.push(el("p", {
       class: "ds-group-note",
       text: head + "原因（GitHub App が入っていない／入っているがこれらのリポジトリが選ばれていない）は、"
@@ -5315,29 +5483,37 @@ ${deriveCapTile.toString()}
   /**
    * すでに入っている App の**インストール設定**（対象リポジトリの追加）へ行くリンク。
    *
-   * **インストールとは別の宛先。** 「installations/new」 は「入れる」ための画面で、
-   * すでに入っている組織の人が押しても対象リポジトリは増えない。
-   * リポジトリの追加は、その人が入れた先（個人 or 組織）の設定画面で行う。
-   *
-   * **組織名を URL に埋め込まない。** 組織ごとの設定ページは
-   * 「github.com/organizations/<組織>/settings/installations」 だが、**その組織の
-   * 管理者でないと 404 になる**。読み取り対象の組織のオーナーが Cortex の利用者とは
-   * 限らない（お客様の組織がまさにそれ）ので、404 に飛ばすより、
-   * 本人のインストール一覧から辿らせるほうが確実に着く。
-   * ——「GITHUB_APP_INSTALL_URL」 の「確かめられないものを顧客に押させない」と同じ判断。
-   *
-   * ⚠ **ただし「押した本人が入れた App」しか出ない。** App を入れたのが別のメンバーや
-   * 顧客側のオーナーなら、着いた先は空になる。だから**案内の本文の側が**
-   * 「App を入れた方の画面に出ます／見当たらない場合はその方にご依頼ください」と断っている
-   * （githubNotConnectedNodes）。**リンクだけ残して本文の断りを消さないこと**——
-   * 消すと「開けば必ずそこにある」前提の案内に戻り、着いた先が空の人が詰む。
+   * **宛先は App 個別ページ（「GITHUB_APP_INSTALL_URL」 と同じ定数・#346）。**
+   * 「infra/lambda/shared/github-gate.mjs」 の 「githubConfigureUrl」 とも同じ宛先なので、
+   * **押す前（この帯・行の補足）と押した後（確認結果の文中）でリンク先が割れない**。
+   * 関数は残してある——呼び手が「入れる」ではなく「設定を開く」意図で呼ぶ場所だから。
+   *
+   * ## なぜ他の2つの宛先を使わないか
+   *
+   * - 個人の一覧 「github.com/settings/installations」 は**「個人アカウントに入れた App」の
+   *   画面**で、組織のインストールは別立て
+   *   （https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps ）。
+   *   押した本人が入れた App しか出ないので、**別の人が入れた組織では空**になる。
+   *   0.12.21 まではこちらを指しており、着いた先が空の人が詰まった（#346）
+   * - 組織の設定ページ 「github.com/organizations/<組織>/settings/installations」 は
+   *   **owner 以外 404**（2026-09-01 オーナーが踏んだ実害）。読み取り対象の組織の
+   *   オーナーが Cortex の利用者とは限らない（お客様の組織がまさにそれ）
+   *
+   * ⚠ **App 個別ページが「導入済みの組織で Configure に着く」ことは、GitHub の文書に
+   * 記述が無い。根拠は 2026-09-02 のオーナーの実測**（cortex-test と GitHub の Configure
+   * 画面で、admin のリポジトリは即追加・admin でないリポジトリには 「request」 タグ）。
+   * 文書化されている一次ソースは次の2つで、**着いた先の画面そのものは書かれていない**:
+   *   - インストール URL と repository admin の設置条件
+   *     https://docs.github.com/en/apps/using-github-apps/installing-a-github-app-from-a-third-party
+   *   - 非オーナーの申請は組織オーナーへ通知される
+   *     https://docs.github.com/en/apps/using-github-apps/requesting-a-github-app-from-your-organization-owner
+   * **GitHub 側の画面が変わったらここが最初に嘘になる。** 宛先を変えるときは
+   * 「githubConfigureUrl」（サーバ）と揃えること。
    */
-  var GITHUB_APP_SETTINGS_URL = "https://github.com/settings/installations";
-
   function appSettingsLink(label) {
     return el("a", {
       class: "ds-owner-install",
-      href: GITHUB_APP_SETTINGS_URL,
+      href: GITHUB_APP_INSTALL_URL,
       target: "_blank", rel: "noopener",
       text: label || "インストール設定を開く →",
     });
@@ -8171,9 +8347,13 @@ ${deriveCapTile.toString()}
    * 「<a>」 の組み立てだけで作る（この画面の他の表示と同じ流儀）。
    *
    * **URL 以外は素のまま出す。** 言い換えると検索できないので、サーバの文言を削らない。
+   *
+   * **行に置くときは 「ds-gate-help」 を付ける**（第2引数）。「.ds-card」 は横並びの flex で、
+   * 自分の行を占めるのは 「flex: 1 1 100%」 の 「.ds-gate-help」 だけ。押した結果で置き換える
+   * とき 「probeSection」 が 「.ds-gate-help」 をまとめて隠すので、この class が要る。
    */
-  function neededNode(text) {
-    var p = el("p", { class: "ds-probe-help" });
+  function neededNode(text, cls) {
+    var p = el("p", { class: cls || "ds-probe-help" });
     splitNeededParts(text).forEach(function (part) {
       if (part.url) p.appendChild(el("a", { href: part.text, target: "_blank", rel: "noopener", text: part.text }));
       else p.appendChild(document.createTextNode(part.text));
@@ -8188,10 +8368,20 @@ ${deriveCapTile.toString()}
    * 「App が入っていない」と「App は入っているがこのリポジトリが選ばれていない」の
    * 言い分けも、設定ページの URL もあちらが決める——**画面で分岐を書き足さない**
    * （書いた瞬間に判定が2箇所になり、夜間の実測とボタンでずれる）。
+   * **ただし admin の定型補足だけは画面の表（DS_GATE_RESTING_HELP）から引く**（#346）——
+   * 「誰がその操作をできるか」はサーバの2つの書き手が別々に文を作るので、片方だけ古くなる。
    */
   function githubProbeHelpNodes(r) {
     if (r.gate === "ok") return [];
-    if (r.needed) return [neededNode(r.needed)];
+    if (r.needed) {
+      var nodes = [neededNode(r.needed)];
+      // 定型の補足（admin なら自分で・でなければ admin に依頼）は**行と同じ表から引く**。
+      // 言い分けと URL はサーバ（needed）、定型の補足だけ画面の表——ここに文を直書きすると
+      // 休止状態の行と押した結果で言うことが割れる。理由と URL は needed が既に持っているので、
+      // 表のパーツ全部ではなく admin の4文（GITHUB_ADMIN_HELP）だけを添える
+      if (restingHelpPartsOf("github", r.gate)) nodes.push(restingHelpNode([GITHUB_ADMIN_HELP], "ds-probe-help"));
+      return nodes;
+    }
     // needed が無いのは gate に落とし込めなかったとき。**生のエラーは隠さない**
     return [el("p", { class: "ds-probe-help", text: "GitHub の応答：" + (r.error || "不明") + "。時間をおいて再度お試しください。" })];
   }
@@ -8440,9 +8630,12 @@ ${deriveCapTile.toString()}
         at.textContent = "いま測った結果（" + (dsFmtTime(j.checkedAt) || "たった今") + "）";
         probeHelpNodes(s, j).forEach(function (n) { body.appendChild(n); });
         // **夜間の判定に添えてあった案内は隠す。** 置き換えた判定と食い違う案内が
-        // 下に残ると、同じ行に2つのことが書いてある状態になる
-        var stale = card.querySelector(".ds-gate-help");
-        if (stale) stale.hidden = true;
+        // 下に残ると、同じ行に2つのことが書いてある状態になる。
+        // **1つ目だけでなく全部隠す（#346）。** 理由文（.ds-gate-reason）・定型補足
+        // （.ds-gate-resting）・DS_GATE の help のどれが付いていても、押した結果と
+        // 食い違う案内を残さない
+        var stale = card.querySelectorAll(".ds-gate-help");
+        for (var si = 0; si < stale.length; si++) stale[si].hidden = true;
         // 表示名を Slack の実名へ自動で揃える（差分表示も更新ボタンも出さない）。
         // **GitHub は揃えない。** 行の名前は owner/repo そのもので、書き換える口
         //（op=config の refresh-channel-name）は channels.json 専用
@@ -10233,7 +10426,11 @@ ${deriveCapTile.toString()}
   }
 
 
-  function extSourceCard(s, meta) {
+  /**
+   * 接続先1件の行。「opts.quietHelp」 が真なら休止状態の補足（#346）を出さない
+   * ——同じリポジトリの2本目の行（Discussions）用で、同じ長文が2行に並ぶのを避ける
+   */
+  function extSourceCard(s, meta, opts) {
     var badges = el("div", { class: "ds-badges" });
     // **Gold 対象かのバッジは持たない。** 一覧に並ぶ Slack チャンネルは例外なく全て対象で、
     // 行ごとに「対象です」と書いても情報が増えない。
@@ -10413,6 +10610,20 @@ ${deriveCapTile.toString()}
     // **ボタンより後ろに置く。** カードは横並びの flex なので、間に挟むと
     // 「登録を解除」が案内文の下の行へ落ちて、既存案件の行の形が変わる
     if (gate.help) card.appendChild(el("p", { class: "ds-gate-help", text: gate.help }));
+    // **最後に測った理由と直し方を、押す前から出す（#346）。** 「アクセス不可 8時間前に確認」
+    // だけでは、押さない人（初見の PM 等）が止まる。表にエントリがある状態は定型の補足
+    // （リンク込み）だけ、無い状態は needed → detail のフォールバック。どちらも ds-gate-help
+    // を付ける——押した結果で置き換えるとき probeSection がまとめて隠す。
+    // **同じリポジトリの2本目の行（Discussions）には出さない**（opts.quietHelp）。
+    // 同じ長文が2行に並ぶと一覧が案内で埋まる。URL のリンク化は neededNode（innerHTML は使わない）
+    if (!(opts && opts.quietHelp) && showsRestingReason(s)) {
+      var restingParts = restingHelpPartsOf(s.type, s.gate);
+      if (restingParts) card.appendChild(restingHelpNode(restingParts, "ds-gate-help ds-gate-resting"));
+      else {
+        var reason = stateReasonOf(s);
+        if (reason) card.appendChild(neededNode(reason, "ds-gate-help ds-gate-reason"));
+      }
+    }
     // 「接続を確認」（2026-08-19）。**押せる人を絞らない**——読むだけで設定を変えないので、
     // 気づいた人がその場で確かめられるほうがよい（オーナー判断）。書き込みになる
     // 「表示名を更新する」は、押した結果の中から別のボタンとして出る（probeSection）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takagaki/cortex-decisions-viewer",
-  "version": "0.12.20",
+  "version": "0.12.22",
   "description": "Cortexの意思決定記録（Decisions/*.md）を静的サイトにビルドして閲覧する。各レコードに「Edit on GitHub」リンクを付与する。",
   "license": "UNLICENSED",
   "private": false,