docs: self-* スコープのユーザーガイド新設(Bolt 2 self-scopes — 260805-docs-impl-sync)

docs/guide/05-scopes-and-depth.ja.md

@@ -6,9 +6,9 @@
 
 ---
 
-## 10 のスコープ
+## 11 の一般スコープ
 
-すべてのワークフローは、名前付きの 10 のスコープのいずれかの下で実行されます。各スコープはステージ集合とデフォルトの深度レベルを定義します。
+すべてのワークフローは、いずれか1つの名前付きスコープの下で実行されます。フレームワークには 15 のスコープが同梱されています — 以下の 11 の一般スコープと、Amadeus 自体の開発にのみ使う 4 つの[自己開発スコープ](#自己開発スコープself-)です。各スコープはステージ集合とデフォルトの深度レベルを定義します。
 
 ### enterprise
 
@@ -93,6 +93,52 @@
 
 複数開発者向けの手動レシピとクレームのセマンティクスについては、[ワークショップモード](workshop-mode.ja.md) を参照してください。
 
+### installer-distribution
+
+**使う場面:** 既存のフレームワークリポジトリに、エンドユーザー向けインストーラーとパッケージ配布経路を追加するとき。
+
+- **ステージ:** 32 のうち 25
+- **デフォルト深度:** Standard
+- **スキップ:** Team Formation(体制は既に確定済み)、両方の Mockup ステージ(インストーラーは CLI 体験であり、その内容は User Stories と Functional Design が受け持つ)、および稼働中のサービスを前提とする4つの運用ステージ — Observability Setup、Incident Response、Performance Validation、Feedback Optimization
+- **自動検出されない:** `keywords: []` のため、`/amadeus --scope installer-distribution` で明示的に選択します
+
+---
+
+## 自己開発スコープ(`self-*`)
+
+4 つのスコープは、あなたのプロジェクトではなく **Amadeus フレームワーク自体**の開発のために存在します。Amadeus を使って自分のソフトウェアを構築している場合、これらを選択することはありません。ここに記載しているのは、`/amadeus --help` やコンパイル済みスコープテーブルに一般スコープと並んで現れるためです。
+
+| スコープ | EXECUTE / 合計 | 深度 | テスト戦略 | 使う場面 |
+|-------|-----------------|-------|---------------|----------|
+| `self-feature` | 14 / 32 | Standard | Comprehensive | Amadeus の実質的な新しい挙動、または複数コンポーネントにまたがる変更 |
+| `self-fix` | 7 / 32 | Minimal | Comprehensive | 既存の契約との整合を回復する、範囲の限定された是正 |
+| `self-refactor` | 8 / 32 | Minimal | Comprehensive | 挙動を保ったまま Amadeus 内部の構造を変える変更 |
+| `self-document` | 9 / 32 | Standard | Minimal | `README*.md` と `docs/` 配下の執筆・更新 |
+
+一般スコープとの違いは2点です。
+
+**決して自動検出されません。** 4 つとも `keywords: []` を宣言しています。スコープ推論はアルファベット順で最初にキーワード一致したものを採るため、`docs` や `refactor` のような一般的な語を主張すると、以降のコールドスタートで別のスコープを恒久的に覆い隠してしまいます。選択は常に明示的です。
+
+```
+/amadeus --scope self-feature
+/amadeus --scope self-fix
+```
+
+**検証は深度に合わせて緩みません。** `self-fix` と `self-refactor` は Minimal 深度で実行されますが `testStrategy: Comprehensive` を維持します。成果物が軽量であることは、build-and-test 境界の軽量化を意味しません — 該当するテスト、生成されたハーネスの parity、`dist:check`、`promote:self:check` はいずれも実行されます。これは、深度から Minimal テストを継承する一般の `fix` / `refactor` スコープとの意図的な差異です。
+
+### self-* スコープの使い分け
+
+すでに存在するものを起点に判断します。
+
+- 意図した挙動や契約が**すでに存在**し、作業がそれとの整合を回復するもの — 不具合、ハーネス間の parity のずれ、生成物やドキュメントの drift、既存のプロジェクト方針の訂正 → `self-fix`。
+- 挙動は**保たれ**、内部構造だけが変わる → `self-refactor`。`self-fix` の経路に functional design を加え、保つべき挙動と目標とする構造を実装前に明示します。
+- **新しい**機能・仕様・アーキテクチャが関わる → `self-feature`。
+- 成果物が**文章**である → `self-document`。
+
+`self-document` が reverse-engineering を第一級のステージとして残しているのは意図的です。ドキュメントは無音で drift します — 3 リリース前に改名されたフラグをページが説明していても、何も失敗しません。そのため、あらゆる記述は「かつてそう言われていた内容」ではなく、実装または git 履歴で実測した事実に遡れる必要があります。build-and-test ステージでは、ドキュメントのゲート(レガシー参照、言語ルール、EN/JA の対応)が実行されます。
+
+`self-feature` は 2026 年 7 月に、完了した intent 群の実績に基づいて軽量化されました。`feasibility`、`approval-handoff`、`practices-discovery`、`nfr-requirements` が SKIP へ移りました — いずれも結果を変えた記録がなく、SKIP のたびに承認ゲートの待ち点が1つ減るためです。個別の intent で本当に必要な場合は、`/amadeus compose` でスキップされたステージを戻せます。
+
 ---
 
 ## スコープルーティングテーブル
@@ -111,6 +157,11 @@
 | `infra` | 13 / 32 | Standard | Standard | インフラ変更 |
 | `security-patch` | 10 / 32 | Minimal | Minimal | CVE 対応 |
 | `workshop` | 25 / 32 | Standard | **Minimal** | AI-DLC ワークショップまたはトレーニングセッション |
+| `installer-distribution` | 25 / 32 | Standard | Standard | エンドユーザー向けインストーラーと配布経路の追加 |
+| `self-feature` | 14 / 32 | Standard | **Comprehensive** | Amadeus 自己開発 — 新しい挙動 |
+| `self-fix` | 7 / 32 | Minimal | **Comprehensive** | Amadeus 自己開発 — 範囲限定の是正 |
+| `self-refactor` | 8 / 32 | Minimal | **Comprehensive** | Amadeus 自己開発 — 構造変更 |
+| `self-document` | 9 / 32 | Standard | **Minimal** | Amadeus 自己開発 — ドキュメント |
 | (自動検出) | 可変 | 可変 | 可変 | AI が自由記述の intent から判定 |
 
 > **プロジェクトごとのデフォルトスコープ:** チームは `.claude/settings.json` に `AMADEUS_DEFAULT_SCOPE` を設定することで、プロジェクトのデフォルトスコープを事前設定できます — 全参加者がフラグを覚えずに `workshop` から開始すべきワークショップに便利です。[カスタマイズ § プロジェクトごとのデフォルトスコープ](13-customization.ja.md#per-project-default-scope) を参照してください。
@@ -310,6 +361,10 @@ You can request different depth or test strategy at any approval gate.
 | スコープ | 深度 | テスト戦略 | なぜ異なるのか? |
 |-------|-------|---------------|----------------|
 | `workshop` | Standard | **Minimal** | 学習のための完全な成果物、ただしペースを保つための高速な Nyquist テスト |
+| `self-feature` | Standard | **Comprehensive** | フレームワークの変更は完全な検証境界を通す必要がある |
+| `self-fix` | Minimal | **Comprehensive** | 成果物は軽量でも、ハーネス parity と配布チェックは実行する |
+| `self-refactor` | Minimal | **Comprehensive** | 挙動が保たれることは仮定せず実証する必要がある |
+| `self-document` | Standard | **Minimal** | 成果物は文章であり、検証はドキュメントのゲートが担う |
 
 その他のすべてのスコープは、テスト戦略を深度から継承します。`--test-strategy` でいつでも上書きできます。
 
@@ -356,6 +411,8 @@ You can request different depth or test strategy at any approval gate.
 | CVE またはセキュリティ脆弱性への対応 | `security-patch` |
 | コンプライアンスを必要とする規制対象機能 | `enterprise` |
 | AI-DLC ワークショップまたはトレーニングラボ | `workshop` |
+| フレームワークリポジトリへのインストーラー追加 | `installer-distribution` |
+| Amadeus フレームワーク自体の開発 | [`self-*` スコープ](#自己開発スコープself-) |
 
 迷ったら `feature` から始めてください — 全 32 ステージを含み、各ステージの承認ゲートで個々のステージをスキップできます。
 

docs/guide/05-scopes-and-depth.md

@@ -6,9 +6,9 @@ Scopes control **which stages execute**. Depth controls **how much detail** each
 
 ---
 
-## The 10 Scopes
+## The 11 General Scopes
 
-Every workflow runs under one of 10 named scopes. Each scope defines a stage set and a default depth level.
+Every workflow runs under one named scope. Fifteen ship with the framework: the 11 general scopes below, plus 4 [self-development scopes](#self-development-scopes-self-) used only for work on Amadeus itself. Each scope defines a stage set and a default depth level.
 
 ### enterprise
 
@@ -93,6 +93,52 @@ Every workflow runs under one of 10 named scopes. Each scope defines a stage set
 
 See [Workshop Mode](workshop-mode.md) for the multi-developer manual recipe and claim semantics.
 
+### installer-distribution
+
+**Use when:** Adding an end-user installer and a package-distribution path to an existing framework repository.
+
+- **Stages:** 25 of 32
+- **Default depth:** Standard
+- **Skips:** Team Formation (the roster is already fixed), both Mockup stages (an installer is a CLI experience, captured in User Stories and Functional Design instead), and the four operation stages that presuppose a running service — Observability Setup, Incident Response, Performance Validation, Feedback Optimization
+- **Not auto-detected:** ships `keywords: []`; reach it with `/amadeus --scope installer-distribution`
+
+---
+
+## Self-development scopes (`self-*`)
+
+Four scopes exist for work on **the Amadeus framework itself**, not on your project. If you are using Amadeus to build your own software you will never select one — they are documented here because they appear in `/amadeus --help` and in the compiled scope table alongside the general scopes.
+
+| Scope | EXECUTE / Total | Depth | Test Strategy | Use when |
+|-------|-----------------|-------|---------------|----------|
+| `self-feature` | 14 / 32 | Standard | Comprehensive | Substantial new Amadeus behavior, or a change spanning components |
+| `self-fix` | 7 / 32 | Minimal | Comprehensive | A bounded correction restoring alignment with an existing contract |
+| `self-refactor` | 8 / 32 | Minimal | Comprehensive | A behavior-preserving structural change to Amadeus internals |
+| `self-document` | 9 / 32 | Standard | Minimal | Writing or updating `README*.md` and everything under `docs/` |
+
+Two properties separate them from the general scopes.
+
+**They are never auto-detected.** All four declare `keywords: []`. Scope inference takes the first alphabetical keyword match, so claiming a generic term like `docs` or `refactor` would permanently shadow another scope on every future cold start. Selection is always explicit:
+
+```
+/amadeus --scope self-feature
+/amadeus --scope self-fix
+```
+
+**Verification does not scale down with depth.** `self-fix` and `self-refactor` run at Minimal depth but keep `testStrategy: Comprehensive`, so lean artifacts never buy a lean build-and-test boundary — applicable tests, generated harness parity, `dist:check`, and `promote:self:check` all still run. This is the deliberate difference from the general `fix` and `refactor` scopes, which inherit Minimal testing from their depth.
+
+### Choosing between the self-* scopes
+
+Start from what already exists:
+
+- The intended behavior or contract **already exists**, and the work restores alignment with it — defects, cross-harness parity gaps, generated or documentation drift, corrections to an existing project policy → `self-fix`.
+- Behavior is **preserved** and only the internal structure changes → `self-refactor`. It follows the `self-fix` route and adds functional design, so the preserved behavior and the target structure are explicit before implementation.
+- A **new** capability, specification, or architecture is involved → `self-feature`.
+- The deliverable is **prose** → `self-document`.
+
+`self-document` keeps reverse-engineering as a first-class stage on purpose. Documentation drifts silently — nothing fails when a page describes a flag that was renamed three releases ago — so every claim has to trace to a measured fact in the implementation or the git history rather than to what the code was once said to do. Its build-and-test stage still runs the documentation gates (legacy references, language rules, EN/JA pairing).
+
+`self-feature` was lightened in July 2026 from evidence across completed intents: `feasibility`, `approval-handoff`, `practices-discovery`, and `nfr-requirements` moved to SKIP because none had a recorded case of changing an outcome, and every SKIP removes an approval-gate wait point. Re-add a skipped stage for a single intent with `/amadeus compose` when it genuinely applies.
+
 ---
 
 ## Scope Routing Table
@@ -111,6 +157,11 @@ Authoritative data lives in the `.claude/scopes/amadeus-<name>.md` files (scope
 | `infra` | 13 / 32 | Standard | Standard | Infrastructure change |
 | `security-patch` | 10 / 32 | Minimal | Minimal | CVE response |
 | `workshop` | 25 / 32 | Standard | **Minimal** | AI-DLC workshop or training session |
+| `installer-distribution` | 25 / 32 | Standard | Standard | Add an end-user installer and distribution path |
+| `self-feature` | 14 / 32 | Standard | **Comprehensive** | Amadeus self-development — new behavior |
+| `self-fix` | 7 / 32 | Minimal | **Comprehensive** | Amadeus self-development — bounded correction |
+| `self-refactor` | 8 / 32 | Minimal | **Comprehensive** | Amadeus self-development — structural change |
+| `self-document` | 9 / 32 | Standard | **Minimal** | Amadeus self-development — documentation |
 | (auto-detect) | Varies | Varies | Varies | AI determines from freeform intent |
 
 > **Per-project default scope:** teams can pre-set the default scope for a project by setting `AMADEUS_DEFAULT_SCOPE` in `.claude/settings.json` — useful for workshops where every participant should start at `workshop` without remembering the flag. See [Customization § Per-Project Default Scope](13-customization.md#per-project-default-scope).
@@ -310,6 +361,10 @@ Test strategy defaults to the **depth level** for most scopes — if your depth
 | Scope | Depth | Test Strategy | Why different? |
 |-------|-------|---------------|----------------|
 | `workshop` | Standard | **Minimal** | Full artifacts for learning, but fast Nyquist testing to keep pace |
+| `self-feature` | Standard | **Comprehensive** | Framework changes must clear the full verification boundary |
+| `self-fix` | Minimal | **Comprehensive** | Lean artifacts, but harness parity and distribution checks still run |
+| `self-refactor` | Minimal | **Comprehensive** | Behavior preservation has to be demonstrated, not assumed |
+| `self-document` | Standard | **Minimal** | Prose deliverable — the documentation gates carry the verification |
 
 All other scopes inherit their test strategy from depth. You can always override with `--test-strategy`.
 
@@ -356,6 +411,8 @@ You can change the test strategy at three points:
 | CVE or security vulnerability response | `security-patch` |
 | Regulated feature requiring compliance | `enterprise` |
 | AI-DLC workshop or training lab | `workshop` |
+| Adding an end-user installer to a framework repo | `installer-distribution` |
+| Work on the Amadeus framework itself | a [`self-*` scope](#self-development-scopes-self-) |
 
 When in doubt, start with `feature` — it includes all 32 stages, and you can skip individual stages at their approval gates.
 

docs/guide/17-skills.ja.md

@@ -130,6 +130,8 @@ basename だけを受け入れ、単一引数として渡します。basename 
 /amadeus --scope poc
 ```
 
+4 つの `self-*` スコープも同じ方法 — `/amadeus --scope self-fix` — で到達します。これらにランナーを用意する予定はありません。あなたのプロジェクトではなく、Amadeus フレームワーク自体の開発に適用されるスコープだからです。それぞれの使い分けは[自己開発スコープ](05-scopes-and-depth.ja.md#自己開発スコープself-) を参照してください。
+
 ワークフローが一度開始すると、そのスコープは `amadeus-state.md` に固定されるため、
 同じランナーを再実行すると、再スタートではなくワークフローを resume します。別の
 スコープで実行するには `/amadeus --scope <name>` を使ってください。

docs/guide/17-skills.md

@@ -109,6 +109,8 @@ You can pass a description and flags straight through, exactly as you would to `
 /amadeus --scope poc
 ```
 
+The four `self-*` scopes are reached the same way — `/amadeus --scope self-fix` — and no runner is planned for them: they apply to work on the Amadeus framework itself, not to your project. See [Self-development scopes](05-scopes-and-depth.md#self-development-scopes-self-) for when each one applies.
+
 Once a workflow has started, its scope is fixed in `amadeus-state.md`, so re-running the same runner resumes the workflow rather than restarting it. To run under a different scope, use `/amadeus --scope <name>`.
 
 ---