Widthdom · Widthdom · Jun 12, 2026 · Jun 12, 2026 · Jun 12, 2026 · Jun 12, 2026
diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md
@@ -94,6 +94,22 @@ or publishing NuGet artifacts:
 dotnet run --project tools/CodeIndex.PackageNormalize -- nupkg/*.nupkg nupkg/*.snupkg
 ```
 
+For release diagnostics, inspect without rewriting and request a bounded
+summary across all candidate packages:
+
+```bash
+dotnet run --project tools/CodeIndex.PackageNormalize -- --dry-run --summary nupkg/*.nupkg nupkg/*.snupkg
+dotnet run --project tools/CodeIndex.PackageNormalize -- --dry-run --json --continue-on-error nupkg/*.nupkg nupkg/*.snupkg
+```
+
+`install.sh` is generated from focused fragments under `install_modules/`.
+After editing installer, doctor, self-test, reinstall, uninstall, or dispatch
+logic, regenerate the checked-in one-file installer before testing:
+
+```bash
+bash tools/build-install-sh.sh
+```
+
 | Normalizer rule | Detail |
 |---|---|
 | Reproducible OPC metadata (#2756) | NuGet's OPC package writer generates a random `package/services/metadata/core-properties/*.psmdcp` part name on each pack run. The normalizer rewrites that part to `package/services/metadata/core-properties/core-properties.psmdcp`, updates the matching content-type and relationship references, and gives ZIP entries stable timestamps. This is the package reproducibility boundary for `.nupkg` and `.snupkg` archives. |
@@ -352,9 +368,13 @@ On startup, `cdidx` walks up from the current directory looking for `.cdidx-vers
 `cdidx upgrade --json` has a stdout contract suitable for automation. Check-only
 and no-update results use the update-check fields
 (`current_version`, `latest_version`, `update_available`, `from_cache`,
-`error`). When an update is installed, installer stdout/stderr is captured so
-stdout remains one JSON document, with `install_attempted`, `install_exit_code`,
-and `install_succeeded` added to the update-check fields.
+`error`) plus release-selection fields (`selected_version`,
+`selected_channel`, `selection_source`, `include_prerelease`). When an update is
+installed, installer stdout/stderr is captured so stdout remains one JSON
+document, with `install_attempted`, `install_exit_code`, and
+`install_succeeded` added to the update-check fields. Windows handoff responses
+also include `handoff_command`, `handoff_url`, `handoff_asset`, and
+`handoff_asset_url`.
 
 ### Degradation reason codes
 
@@ -2221,6 +2241,22 @@ package normalization を実行します:
 dotnet run --project tools/CodeIndex.PackageNormalize -- nupkg/*.nupkg nupkg/*.snupkg
 ```
 
+release diagnostics では、書き換えずに検査し、candidate package 全体の bounded
+summary を取得できます:
+
+```bash
+dotnet run --project tools/CodeIndex.PackageNormalize -- --dry-run --summary nupkg/*.nupkg nupkg/*.snupkg
+dotnet run --project tools/CodeIndex.PackageNormalize -- --dry-run --json --continue-on-error nupkg/*.nupkg nupkg/*.snupkg
+```
+
+`install.sh` は `install_modules/` 配下の focused fragment から生成されます。
+installer、doctor、self-test、reinstall、uninstall、dispatch logic を変更した場合は、
+テスト前に checked-in の単一ファイル installer を再生成してください:
+
+```bash
+bash tools/build-install-sh.sh
+```
+
 | normalizer rule | 詳細 |
 |---|---|
 | 再現可能な OPC metadata (#2756) | NuGet の OPC package writer は `package/services/metadata/core-properties/*.psmdcp` part 名を pack ごとにランダム生成します。normalizer はその part を `package/services/metadata/core-properties/core-properties.psmdcp` に書き換え、対応する content-type / relationship 参照も更新し、ZIP entry timestamp を固定します。これが `.nupkg` / `.snupkg` archive の package 再現性境界です。 |
@@ -2531,10 +2567,13 @@ latest release の installer を実行します。
 
 `cdidx upgrade --json` は automation 向けの stdout contract を持ちます。check-only と
 no-update の結果は update-check fields (`current_version`, `latest_version`,
-`update_available`, `from_cache`, `error`) を使います。update を install する場合、
-installer stdout/stderr は capture されるため stdout は 1 個の JSON document のままになり、
-update-check fields に `install_attempted`、`install_exit_code`、`install_succeeded` が
-追加されます。
+`update_available`, `from_cache`, `error`) に release-selection fields
+(`selected_version`, `selected_channel`, `selection_source`, `include_prerelease`)
+を加えたものを使います。update を install する場合、installer stdout/stderr は
+capture されるため stdout は 1 個の JSON document のままになり、update-check fields に
+`install_attempted`、`install_exit_code`、`install_succeeded` が追加されます。Windows
+handoff response には `handoff_command`、`handoff_url`、`handoff_asset`、
+`handoff_asset_url` も含まれます。
 
 ### 劣化理由コード
 

diff --git a/USER_GUIDE.md b/USER_GUIDE.md
@@ -580,6 +580,22 @@ automatically when the `gh` command is available and the public GitHub release
 host is used. Set `CDIDX_REQUIRE_ATTESTATION=1` to make the installer fail
 closed when provenance verification cannot be completed.
 
+Installer verification policy is explicit:
+
+- `CDIDX_VERIFY_POLICY=compat` is the default. The installer always enforces
+  archive checksums, runs GitHub attestation and GPG checksum-signature checks
+  when the required tools/configuration are available, and warns before
+  continuing when an optional second-channel check cannot run.
+- `CDIDX_VERIFY_POLICY=strict` or `--verify-policy strict` makes public GitHub
+  attestation and GPG checksum-signature verification fail closed. Strict mode
+  also requires signer fingerprint pinning through
+  `CDIDX_RELEASE_GPG_FINGERPRINT`.
+- `CDIDX_REQUIRE_ATTESTATION=1` and `CDIDX_STRICT_VERIFY=1` remain available as
+  narrower compatibility knobs when only one second-channel check should be
+  required. Until an official default release-signing fingerprint is bundled,
+  strict GPG verification requires operators to distribute the trusted
+  fingerprint through `CDIDX_RELEASE_GPG_FINGERPRINT`.
+
 ### Option A: One-liner install (no .NET required)
 
 Works in containers, CI, and any Linux/macOS environment — no .NET SDK needed.
@@ -652,6 +668,31 @@ bash ./install.sh --self-test-local-mirror
 If the default local self-test port is busy, set
 `CDIDX_LOCAL_MIRROR_PORT=18766`.
 
+#### Upgrade an install.sh installation
+
+`cdidx upgrade` checks GitHub releases and reruns the verified installer for
+the selected release. It defaults to the stable/latest release channel.
+
+```bash
+cdidx upgrade
+cdidx upgrade --check-only --json
+cdidx upgrade --prerelease
+cdidx upgrade --channel prerelease
+cdidx upgrade --version v1.29.0-rc.1
+```
+
+Use `--channel stable` (or `--channel latest`) to stay on stable releases,
+`--prerelease` / `--channel prerelease` to dogfood the newest prerelease, and
+`--version <tag>` to install a specific release tag. JSON output includes
+`selected_version`, `selected_channel`, `selection_source`, and
+`include_prerelease` so automation can record why a release was selected.
+
+On Windows, `cdidx upgrade` selects the same release but does not replace the
+running binary in place. It prints a NuGet handoff command such as
+`dotnet tool update -g cdidx --version <version>` plus the matching release
+page and `CodeIndex-win-*.zip` asset URL; JSON output carries those values in
+`handoff_command`, `handoff_url`, `handoff_asset`, and `handoff_asset_url`.
+
 ### Option B: NuGet Global Tool
 
 Requires the [.NET 8.x SDK](https://dotnet.microsoft.com/download/dotnet/8.0)
@@ -2934,6 +2975,22 @@ installer はこの provenance verification を自動実行します。
 `CDIDX_REQUIRE_ATTESTATION=1` を設定すると、provenance verification を完了
 できない場合に installer は fail closed します。
 
+installer の verification policy は明示的です:
+
+- 既定は `CDIDX_VERIFY_POLICY=compat` です。installer は archive checksum を常に
+  検証し、必要な tool/configuration がある場合は GitHub attestation と GPG
+  checksum-signature verification を実行します。任意の second-channel check を
+  実行できない場合は警告して続行します。
+- `CDIDX_VERIFY_POLICY=strict` または `--verify-policy strict` は、public GitHub
+  attestation と GPG checksum-signature verification を fail closed にします。
+  strict mode では `CDIDX_RELEASE_GPG_FINGERPRINT` による signer fingerprint
+  pinning も必須です。
+- `CDIDX_REQUIRE_ATTESTATION=1` と `CDIDX_STRICT_VERIFY=1` は、片方の
+  second-channel check だけを必須化したい場合の互換 knob として残っています。
+  公式の default release-signing fingerprint が bundled されるまでは、strict GPG
+  verification を使う operator が信頼する fingerprint を
+  `CDIDX_RELEASE_GPG_FINGERPRINT` 経由で配布してください。
+
 GitHub attestation は、その artifact が repository workflow identity により
 生成されたことを検証します。
 
@@ -3009,6 +3066,32 @@ bash ./install.sh --self-test-local-mirror
 既定の local self-test port が埋まっている場合は
 `CDIDX_LOCAL_MIRROR_PORT=18766` を設定してください。
 
+#### install.sh で入れた cdidx のアップグレード
+
+`cdidx upgrade` は GitHub releases を確認し、選択した release に対して検証済み
+installer を再実行します。既定では stable/latest release channel を使います。
+
+```bash
+cdidx upgrade
+cdidx upgrade --check-only --json
+cdidx upgrade --prerelease
+cdidx upgrade --channel prerelease
+cdidx upgrade --version v1.29.0-rc.1
+```
+
+stable release に留まる場合は `--channel stable`（または `--channel latest`）、
+最新 prerelease を試す場合は `--prerelease` / `--channel prerelease`、特定
+release tag を入れる場合は `--version <tag>` を使います。JSON 出力には
+`selected_version`、`selected_channel`、`selection_source`、
+`include_prerelease` が含まれるため、automation 側で選択理由を記録できます。
+
+Windows では `cdidx upgrade` は同じ release を選択しますが、実行中 binary を
+その場では置き換えません。代わりに
+`dotnet tool update -g cdidx --version <version>` 形式の NuGet handoff command
+と、対応する release page / `CodeIndex-win-*.zip` asset URL を表示します。JSON 出力では
+`handoff_command`、`handoff_url`、`handoff_asset`、`handoff_asset_url` に
+同じ値が入ります。
+
 ### 方法B: NuGet グローバルツール
 
 `dotnet tool install` / `dotnet tool update` には

diff --git a/changelog.d/unreleased/3374.added.md b/changelog.d/unreleased/3374.added.md
@@ -0,0 +1,18 @@
+---
+category: added
+issues:
+  - 3374
+affected:
+  - src/CodeIndex/Cli/ProgramRunner.cs
+  - src/CodeIndex/Cli/JsonOutputContracts.cs
+  - tests/CodeIndex.Tests/ProgramRunnerTests.cs
+  - USER_GUIDE.md
+---
+
+## English
+
+- **Windows upgrade now reports a first-class handoff path (#3374)** — when `cdidx upgrade` runs on Windows, it returns a NuGet update command plus release page and matching `CodeIndex-win-*.zip` asset details in human and JSON output instead of only reporting an unsupported platform.
+
+## 日本語
+
+- **Windows upgrade が first-class handoff path を返すようになりました (#3374)** — Windows で `cdidx upgrade` を実行した場合、単なる unsupported platform ではなく、NuGet update command と release page、対応する `CodeIndex-win-*.zip` asset 情報を human / JSON 出力で返します。
diff --git a/changelog.d/unreleased/3375.added.md b/changelog.d/unreleased/3375.added.md
@@ -0,0 +1,24 @@
+---
+category: added
+issues:
+  - 3375
+affected:
+  - src/CodeIndex/Cli/CliFlagSchema.cs
+  - src/CodeIndex/Cli/ConsoleUi.cs
+  - src/CodeIndex/Cli/ProgramRunner.cs
+  - src/CodeIndex/Cli/UpdateChecker.cs
+  - src/CodeIndex/Cli/JsonOutputContracts.cs
+  - tests/CodeIndex.Tests/CliFlagSchemaTests.cs
+  - tests/CodeIndex.Tests/ConsoleUiTests.cs
+  - tests/CodeIndex.Tests/ProgramRunnerTests.cs
+  - DEVELOPER_GUIDE.md
+  - USER_GUIDE.md
+---
+
+## English
+
+- **Upgrade can now select stable, prerelease, or explicit release tags (#3375)** — `cdidx upgrade` accepts `--channel stable|prerelease`, `--prerelease`, and `--version <tag>`, and JSON output now reports the selected version, channel, selection source, and prerelease inclusion.
+
+## 日本語
+
+- **upgrade で stable、prerelease、明示 release tag を選択できるようにしました (#3375)** — `cdidx upgrade` は `--channel stable|prerelease`、`--prerelease`、`--version <tag>` を受け付け、JSON 出力で選択 version、channel、selection source、prerelease inclusion を返します。
diff --git a/changelog.d/unreleased/3498.internal.md b/changelog.d/unreleased/3498.internal.md
@@ -0,0 +1,19 @@
+---
+category: internal
+issues:
+  - 3498
+affected:
+  - install.sh
+  - install_modules/
+  - tools/build-install-sh.sh
+  - tests/CodeIndex.Tests/InstallScriptTests.cs
+  - DEVELOPER_GUIDE.md
+---
+
+## English
+
+- **Split the one-file installer source into focused generated fragments (#3498)** — `install.sh` is now generated from dedicated installer, path guidance, uninstall, self-test, reinstall, doctor, and dispatch fragments, with tests that keep the generated one-liner synchronized.
+
+## 日本語
+
+- **単一ファイル installer の source を focused fragment に分割しました (#3498)** — `install.sh` は installer、PATH guidance、uninstall、self-test、reinstall、doctor、dispatch 用の fragment から生成されるようになり、生成された one-liner との同期をテストで固定します。
diff --git a/changelog.d/unreleased/3502.security.md b/changelog.d/unreleased/3502.security.md
@@ -0,0 +1,19 @@
+---
+category: security
+issues:
+  - 3502
+affected:
+  - install.sh
+  - install_modules/00-core-and-verification.sh
+  - install_modules/90-dispatch.sh
+  - tests/CodeIndex.Tests/InstallScriptTests.cs
+  - USER_GUIDE.md
+---
+
+## English
+
+- **Installer verification policy is now explicit (#3502)** — `CDIDX_VERIFY_POLICY=compat` remains the default warning-compatible mode, while `CDIDX_VERIFY_POLICY=strict` or `--verify-policy strict` fail closed on missing GitHub attestation, GPG signature verification, or signer fingerprint pinning.
+
+## 日本語
+
+- **installer の verification policy を明示しました (#3502)** — 既定は警告互換の `CDIDX_VERIFY_POLICY=compat` のまま、`CDIDX_VERIFY_POLICY=strict` または `--verify-policy strict` では GitHub attestation、GPG signature verification、signer fingerprint pinning が欠けた場合に fail closed します。
diff --git a/changelog.d/unreleased/3553.added.md b/changelog.d/unreleased/3553.added.md
@@ -0,0 +1,17 @@
+---
+category: added
+issues:
+  - 3553
+affected:
+  - tools/CodeIndex.PackageNormalize/PackageNormalizeCli.cs
+  - tests/CodeIndex.Tests/ReleaseWorkflowTests.cs
+  - DEVELOPER_GUIDE.md
+---
+
+## English
+
+- **PackageNormalize now supports release diagnostics without rewriting packages (#3553)** — `--dry-run` / `--check`, `--summary`, `--json`, and `--continue-on-error` report inspected, normalized, unchanged, failed, and skipped package counts while keeping positional-only normalization compatible.
+
+## 日本語
+
+- **PackageNormalize が package を書き換えない release diagnostics に対応しました (#3553)** — `--dry-run` / `--check`、`--summary`、`--json`、`--continue-on-error` により inspected、normalized、unchanged、failed、skipped の package 件数を返しつつ、従来の positional-only normalize 挙動は維持します。