diff --git a/README.ja.md b/README.ja.md index 7eef902e37..e7c5192b30 100644 --- a/README.ja.md +++ b/README.ja.md @@ -4,7 +4,7 @@ **Amadeus-DLC はセルフホスト型の AI 開発ライフサイクルです。決定的なワークフローエンジンと、ゲート付き32ステージのメソドロジーを一度だけ記述し、8つのコーディングエージェントハーネスの上でネイティブに動かします。** あなたは「何を作るか」を記述するだけ — 11のドメイン専門家エージェントが ideation・inception・construction・operation を進め、プロンプトではなく**コードとして実装された状態機械**が、あなたが通すまですべての承認ゲートを保持します。 -![version](https://img.shields.io/badge/version-0.1.3-blue) +![version](https://img.shields.io/badge/version-0.1.7-blue) ![license](https://img.shields.io/badge/license-(MIT%20OR%20Apache--2.0)-green) ![Kiro IDE](https://img.shields.io/badge/harness-Kiro%20IDE-orange) ![Kiro CLI](https://img.shields.io/badge/harness-Kiro%20CLI-orange) @@ -12,6 +12,8 @@ ![Codex CLI](https://img.shields.io/badge/harness-Codex%20CLI-orange) ![OpenCode](https://img.shields.io/badge/harness-OpenCode-orange) ![Cursor](https://img.shields.io/badge/harness-Cursor-orange) +![Kimi Code](https://img.shields.io/badge/harness-Kimi%20Code-orange) +![Pi Coding Agent](https://img.shields.io/badge/harness-Pi%20Coding%20Agent-orange) > [!WARNING] > **プレビュー版(pre-1.0)— 活発に開発中です。** インターフェース、ステージ定義、エージェント構成、インストールモデルは進化の途上にあり、リリース間で破壊的変更が入ることがあります。依存するものには既知の安定バージョンをピン留めし、生成された出力はすべて確認してから利用してください。 @@ -81,7 +83,7 @@ Amadeus-DLC は AWS が定義した **AI-DLC メソドロジー**(段階的・ | **OpenCode** | — | `bunx @amadeus-dlc/setup install --harness opencode` | `$amadeus` | [OpenCode で動かす](docs/guide/harnesses/opencode.ja.md) | | **Kiro IDE** | — | `bunx @amadeus-dlc/setup install --harness kiro-ide` | `/amadeus` | [Kiro IDE で動かす](docs/guide/harnesses/kiro-ide.ja.md) | | **Kiro CLI** | ≥ 2.6 | `bunx @amadeus-dlc/setup install --harness kiro` | `/amadeus` | [Kiro CLI で動かす](docs/guide/harnesses/kiro-cli.ja.md) | -| **Kimi Code** | ≥ 0.28.1 | `bunx @amadeus-dlc/setup install --harness kimi` | `/skill:amadeus` | [Kimi Code で動かす](docs/guide/harnesses/kimi-code.ja.md) | +| **Kimi Code** | ≥ 0.29.0 | `bunx @amadeus-dlc/setup install --harness kimi` | `/skill:amadeus` | [Kimi Code で動かす](docs/guide/harnesses/kimi-code.ja.md) | | **Pi Coding Agent** | ≥ 0.83.0 | `bunx @amadeus-dlc/setup install --harness pi` | `/skill:amadeus` | [Pi Coding Agent で動かす](docs/guide/harnesses/pi.ja.md) | > [!NOTE] @@ -121,7 +123,7 @@ Windows では PowerShell と CMD の*どちらか一方*を使ってくださ bunx @amadeus-dlc/setup install ``` -引数なしの `install` は対話ウィザードを起動します: ハーネス(`claude` / `codex` / `kiro` / `kiro-ide` / `opencode` / `cursor` / `kimi`)とターゲットディレクトリを選ぶだけです。スクリプトや CI ではフラグで明示します: +引数なしの `install` は対話ウィザードを起動します: ハーネス(`claude` / `codex` / `kiro` / `kiro-ide` / `opencode` / `cursor` / `kimi` / `pi`)とターゲットディレクトリを選ぶだけです。スクリプトや CI ではフラグで明示します: ```bash bunx @amadeus-dlc/setup install --harness claude --target your-project --yes @@ -296,7 +298,7 @@ amadeus/ │ │ │ ├── skills/ # セッションスキル │ │ │ └── templates/ # オンボーディング雛形 → 各ハーネスの CLAUDE.md / AGENTS.md │ │ └── harness/ # ハーネスごとの薄い表層 — 小さく、意図的に分岐 -│ │ ├── claude/ codex/ cursor/ kimi/ kiro/ kiro-ide/ opencode/ +│ │ ├── claude/ codex/ cursor/ kimi/ kiro/ kiro-ide/ opencode/ pi/ │ └── setup/ # @amadeus-dlc/setup — インストーラパッケージ │ ├── scripts/ @@ -307,7 +309,7 @@ amadeus/ │ ─────────── 生成物(未追跡・使い捨てのローカル出力) ─────────── ├── dist/ │ ├── claude/ kiro-ide/ kiro/ # 各ハーネスのユーザーがコピーするもの -│ ├── codex/ opencode/ cursor/ kimi/ +│ ├── codex/ opencode/ cursor/ kimi/ pi/ │ │ ─────────── 支援 ─────────── ├── tests/ # 全 TypeScript のテストスイート(t*.test.ts) diff --git a/README.md b/README.md index 40c5535522..0575a35a13 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ ![Codex CLI](https://img.shields.io/badge/harness-Codex%20CLI-orange) ![OpenCode](https://img.shields.io/badge/harness-OpenCode-orange) ![Cursor](https://img.shields.io/badge/harness-Cursor-orange) +![Kimi Code](https://img.shields.io/badge/harness-Kimi%20Code-orange) +![Pi Coding Agent](https://img.shields.io/badge/harness-Pi%20Coding%20Agent-orange) > [!WARNING] > **Preview (pre-1.0) — under active development.** Interfaces, stage definitions, the agent roster, and the install model are still evolving, and breaking changes can land between releases. Pin a known-good version for anything you depend on, and review all generated output before you act on it. @@ -81,7 +83,7 @@ The engine — state machine, audit log, referee — is byte-identical across ev | **OpenCode** | — | `bunx @amadeus-dlc/setup install --harness opencode` | `$amadeus` | [Running on OpenCode](docs/guide/harnesses/opencode.md) | | **Kiro IDE** | — | `bunx @amadeus-dlc/setup install --harness kiro-ide` | `/amadeus` | [Running on Kiro IDE](docs/guide/harnesses/kiro-ide.md) | | **Kiro CLI** | ≥ 2.6 | `bunx @amadeus-dlc/setup install --harness kiro` | `/amadeus` | [Running on Kiro CLI](docs/guide/harnesses/kiro-cli.md) | -| **Kimi Code** | ≥ 0.28.1 | `bunx @amadeus-dlc/setup install --harness kimi` | `/skill:amadeus` | [Running on Kimi Code](docs/guide/harnesses/kimi-code.md) | +| **Kimi Code** | ≥ 0.29.0 | `bunx @amadeus-dlc/setup install --harness kimi` | `/skill:amadeus` | [Running on Kimi Code](docs/guide/harnesses/kimi-code.md) | | **Pi Coding Agent** | ≥ 0.83.0 | `bunx @amadeus-dlc/setup install --harness pi` | `/skill:amadeus` | [Running on Pi Coding Agent](docs/guide/harnesses/pi.md) | > [!NOTE] @@ -121,7 +123,7 @@ On Windows, use *either* PowerShell *or* CMD, not both — your prompt shows `PS bunx @amadeus-dlc/setup install ``` -Run bare, `install` launches an interactive wizard: pick your harness (`claude` / `codex` / `kiro` / `kiro-ide` / `opencode` / `cursor` / `kimi`), then a target directory. For scripts and CI, skip the wizard with explicit flags: +Run bare, `install` launches an interactive wizard: pick your harness (`claude` / `codex` / `kiro` / `kiro-ide` / `opencode` / `cursor` / `kimi` / `pi`), then a target directory. For scripts and CI, skip the wizard with explicit flags: ```bash bunx @amadeus-dlc/setup install --harness claude --target your-project --yes @@ -296,7 +298,7 @@ amadeus/ │ │ │ ├── skills/ # session skills │ │ │ └── templates/ # onboarding skeleton → each harness's CLAUDE.md / AGENTS.md │ │ └── harness/ # thin per-harness authored surfaces — small, divergent by design -│ │ ├── claude/ codex/ cursor/ kimi/ kiro/ kiro-ide/ opencode/ +│ │ ├── claude/ codex/ cursor/ kimi/ kiro/ kiro-ide/ opencode/ pi/ │ └── setup/ # @amadeus-dlc/setup — the installer package │ ├── scripts/ @@ -307,7 +309,7 @@ amadeus/ │ ─────────── GENERATED, IGNORED, DISPOSABLE LOCAL OUTPUT ─────────── ├── dist/ │ ├── claude/ kiro-ide/ kiro/ # what users of each harness copy -│ ├── codex/ opencode/ cursor/ kimi/ +│ ├── codex/ opencode/ cursor/ kimi/ pi/ │ │ ─────────── SUPPORTING ─────────── ├── tests/ # all-TypeScript suite (t*.test.ts) diff --git a/docs/README.ja.md b/docs/README.ja.md index 91c027e4fc..733e878790 100644 --- a/docs/README.ja.md +++ b/docs/README.ja.md @@ -2,7 +2,7 @@ > 言語: [English](README.md) | **日本語** -**AI-DLC は方法論です** — AI 駆動のソフトウェア開発に対する、構造化されゲートで区切られたアプローチ(AWS によって定義)。**このリポジトリはそのネイティブなマルチハーネス実装です:** 方法論を、ハーネス非依存の単一の `packages/framework/core/` からスキル・エージェント・フック・ツールとしてレンダリングしているため、あなたが使う CLI ハーネス上でネイティブに動作します — 現時点では Claude Code、Kiro CLI、Kiro IDE、Codex CLI、そしてあなたが移植できる任意の対応 CLI です。方法論は *何をするか* であり、各ハーネスの配布物は 1 つのランタイムに対する *どう動かすか* であって、すべての配布物は同じソースから生成されます。 +**AI-DLC は方法論です** — AI 駆動のソフトウェア開発に対する、構造化されゲートで区切られたアプローチ(AWS によって定義)。**このリポジトリはそのネイティブなマルチハーネス実装です:** 方法論を、ハーネス非依存の単一の `packages/framework/core/` からスキル・エージェント・フック・ツールとしてレンダリングしているため、あなたが使う CLI ハーネス上でネイティブに動作します — 現時点では Claude Code、Codex CLI、Cursor、OpenCode、Kiro CLI、Kiro IDE、Kimi Code、Pi Coding Agent、そしてあなたが移植できる任意の対応 CLI です。方法論は *何をするか* であり、各ハーネスの配布物は 1 つのランタイムに対する *どう動かすか* であって、すべての配布物は同じソースから生成されます。 初めてですか? [README](../README.ja.md) にインストールのクイックスタートと「ハーネスを選ぶ」の表があります。このページはドキュメント自体の地図です。 @@ -25,6 +25,7 @@ Harness Engineer Guide と Developer Reference の境界は **データ対コー ## ビルドと貢献 メンテナは `packages/framework/core/` で著述し、`bun run dist`(`bun scripts/package.ts`)で `dist//` ツリーを再生成します — 完全なビルド&テストのループについては [Contributing Guide](reference/11-contributing.ja.md) を、ハーネスの追加については [Porting to a New Harness](harness-engineering/09-porting-to-a-new-harness.ja.md) を参照してください。 +ハーネス配布物への変更を出荷する前には、[実ハーネスのエンドツーエンド検証](harness-engineering/live-e2e.ja.md) のopt-inなローカルジャーニーを実行してください。 ## 本家 AI-DLC v2の違い @@ -36,6 +37,8 @@ Harness Engineer Guide と Developer Reference の境界は **データ対コー - [形式モデルを実装に追従させる](reference/21-formal-model-following.ja.md) - [新規プロトコルへ形式モデルを供給する](reference/22-formal-model-supply.ja.md) - [Telemetry Schema reference](reference/23-telemetry-schema.ja.md) +- [Intent autonomy・レビュー・完了](reference/24-intent-autonomy.ja.md) +- [AI-DLC v2 生成ファイル完全目録](amadeus-files.ja.md) リポジトリレイアウトの設計判断は [Workspace Layout Decision](reference/18-workspace-layout.ja.md) に記録しています。 diff --git a/docs/README.md b/docs/README.md index 1b3be52360..4fde29b88c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,7 +6,8 @@ development (defined by AWS). **This repository is its native, multi-harness implementation:** the methodology rendered as skills, agents, hooks, and tools from one harness-neutral `packages/framework/core/`, so it runs natively in the CLI harness you use -— today Claude Code, Kiro CLI, Kiro IDE, or Codex CLI, and any capable CLI you port it to. +— today Claude Code, Codex CLI, Cursor, OpenCode, Kiro CLI, Kiro IDE, Kimi Code, or +Pi Coding Agent, and any capable CLI you port it to. The methodology is the *what*; each harness distribution is the *how* for one runtime, and every distribution is generated from the same source. @@ -39,6 +40,7 @@ Maintainers author in `packages/framework/core/` and `packages/framework/harness `bun run dist` (`bun scripts/package.ts`) — see the [Contributing Guide](reference/11-contributing.md) for the full build-and-test loop, and [Porting to a New Harness](harness-engineering/09-porting-to-a-new-harness.md) to add one. +Before shipping a change to a harness distribution, run the opt-in local journeys in [Live Harness End-to-End Verification](harness-engineering/live-e2e.md). ## Upstream AI-DLC v2 differences @@ -50,6 +52,8 @@ to add one. - [Keeping a formal model in step with its implementation](reference/21-formal-model-following.md) - [Supplying a formal model for a new protocol](reference/22-formal-model-supply.md) - [Telemetry Schema reference](reference/23-telemetry-schema.md) +- [Intent autonomy, review, and completion](reference/24-intent-autonomy.md) +- [Complete AI-DLC v2 Generated File Inventory](amadeus-files.md) The repository layout decision is recorded in [Workspace Layout Decision](reference/18-workspace-layout.md): the framework diff --git a/docs/amadeus-files.ja.md b/docs/amadeus-files.ja.md index f53ffae109..25e9177329 100644 --- a/docs/amadeus-files.ja.md +++ b/docs/amadeus-files.ja.md @@ -2,10 +2,11 @@ > 言語: [English](amadeus-files.md) | **日本語** -出典(一次情報): `amadeus-dlc/amadeus` v2ブランチ(commit 9b77786, 2026-07時点) +出典(一次情報): `amadeus-dlc/amadeus`(commit f4d99c2c9, 2026-08時点) - 公式リファレンス: `docs/guide/14-artifacts-reference.md`(ディレクトリツリー・git方針) - ワークスペース構造: `docs/guide/03-spaces-and-intents.md` -- 正確なファイル名: `packages/framework/core/amadeus-common/stages/*/*.md` 全32ステージのfrontmatter `outputs:` から抽出 +- 生成ツリー: `bun run dist` の出力(`dist/claude/.claude`、`dist/codex/.codex`、`dist/codex/.agents`)を実測 +- 正確なファイル名: `packages/framework/core/amadeus-common/stages/*/*.md` 全32ステージのfrontmatter `produces:` から抽出 --- @@ -13,6 +14,8 @@ ``` .agents/ # Codexが読むskill配布先(.codex/の兄弟) +├── rules/ # Codex向けAI-DLCルールの入口 +│ └── amadeus.md └── skills/ ├── amadeus/ # オーケストレーターskill └── amadeus-/ # stage runner / scope runner skill @@ -29,8 +32,10 @@ │ ├── inception/ │ ├── construction/ │ └── operation/ -├── hooks/ # Claude Code hook本体(フレームワークのフック) +├── hooks/ # Claude Code hook本体(フレームワークのフック + Claude用ディスパッチャ) │ ├── amadeus-audit-logger.ts +│ ├── amadeus-dispatch.ts +│ ├── amadeus-log-subagent-start.ts │ ├── amadeus-log-subagent.ts │ ├── amadeus-mint-presence.ts │ ├── amadeus-plugin-compose.ts @@ -45,28 +50,35 @@ ├── knowledge/ # フレームワーク方法論知識(共有 + agent別) │ ├── amadeus-shared/ │ └── amadeus--agent/ +├── otel/ # OpenTelemetryプロバイダ層(全ハーネスへ配布) ├── rules/ # Claude Code側のAI-DLCルール入口 │ └── amadeus.md ├── scopes/ # scope定義(amadeus-mvp等) │ └── amadeus-.md ├── sensors/ # 決定論センサー定義 │ ├── amadeus-answer-evidence.md +│ ├── amadeus-event-registry-drift.md │ ├── amadeus-linter.md │ ├── amadeus-model-completeness.md │ ├── amadeus-required-sections.md +│ ├── amadeus-self-scope-consistency.md │ ├── amadeus-type-check.md │ └── amadeus-upstream-coverage.md ├── skills/ # Claude Code skill(オーケストレーター + stage runner) │ ├── amadeus/ │ └── amadeus-/ -├── tools/ # Bunで実行する決定論エンジン/CLI(26本 + data/) +├── tools/ # Bunで実行する決定論エンジン/CLI(amadeus-*.ts + data/) │ ├── amadeus-*.ts │ └── data/ +│ ├── harness.json │ ├── stage-graph.json +│ ├── stage-identities.json │ ├── scope-grid.json +│ ├── self-install-allowlist.ts │ ├── memory-seed/ │ ├── scaffold/ │ └── templates/ +├── vendor/ # ベンダリングしたOpenTelemetry API(全ハーネスへ配布) ├── CLAUDE.md # Claude Code向け導入指示 ├── CLAUDE.md.example ├── settings.json # hook/statusline/permission設定 @@ -83,7 +95,9 @@ │ └── stages/ ├── hooks/ # Codex hook本体(Claude共通のフレームワークフック + Codex adapter) │ ├── amadeus-codex-adapter.ts +│ ├── amadeus-codex-hook-runtime.ts │ ├── amadeus-audit-logger.ts +│ ├── amadeus-log-subagent-start.ts │ ├── amadeus-log-subagent.ts │ ├── amadeus-mint-presence.ts │ ├── amadeus-plugin-compose.ts @@ -98,25 +112,32 @@ ├── knowledge/ # フレームワーク方法論知識(共有 + agent別) │ ├── amadeus-shared/ │ └── amadeus--agent/ +├── otel/ # OpenTelemetryプロバイダ層(全ハーネスへ配布) ├── rules/ # Codex permission rules。AI-DLC memory層とは別物 │ └── default.rules ├── scopes/ # scope定義(amadeus-mvp等) │ └── amadeus-.md ├── sensors/ # 決定論センサー定義 │ ├── amadeus-answer-evidence.md +│ ├── amadeus-event-registry-drift.md │ ├── amadeus-linter.md │ ├── amadeus-model-completeness.md │ ├── amadeus-required-sections.md +│ ├── amadeus-self-scope-consistency.md │ ├── amadeus-type-check.md │ └── amadeus-upstream-coverage.md -├── tools/ # Bunで実行する決定論エンジン/CLI(26本 + data/) +├── tools/ # Bunで実行する決定論エンジン/CLI(amadeus-*.ts + data/) │ ├── amadeus-*.ts │ └── data/ +│ ├── harness.json │ ├── stage-graph.json +│ ├── stage-identities.json │ ├── scope-grid.json +│ ├── self-install-allowlist.ts │ ├── memory-seed/ │ ├── scaffold/ │ └── templates/ +├── vendor/ # ベンダリングしたOpenTelemetry API(全ハーネスへ配布) ├── config.toml # Codexプロジェクト設定(必要時のみ) ├── config.toml.example ├── hooks.json # Codex hookのactive file(per-clone、可変、gitignore) @@ -247,7 +268,7 @@ amadeus/ | 3.3 nfr-design | `performance-design.md`, `security-design.md`, `scalability-design.md`, `reliability-design.md`, `logical-components.md` | 計画次第・per unit | | 3.4 infrastructure-design | `deployment-architecture.md`, `infrastructure-services.md`, `monitoring-design.md`, `cicd-pipeline.md`, (条件付き) `shared-infrastructure.md` | 計画次第・per unit | | 3.5 code-generation | `code-generation-plan.md`(チェックボックス+story追跡), `code-summary.md`(コード本体はrecord dirではなくコードリポジトリへ) | 常時・per unit | -| 3.6 build-and-test | `build-instructions.md`, `unit-test-instructions.md`, `integration-test-instructions.md`, `performance-test-instructions.md`, `security-test-instructions.md`, `build-and-test-summary.md`, `test-results.md` | 常時・全Unit後 | +| 3.6 build-and-test | `build-instructions.md`, `unit-test-instructions.md`, `integration-test-instructions.md`, `performance-test-instructions.md`, `security-test-instructions.md`, `build-and-test-summary.md`, `build-test-results.md` | 常時・全Unit後 | | 3.7 ci-pipeline | `ci-config.md`, `quality-gates.md` | 条件付き・全Unit後 | ### 2.6 Operation(4.1–4.7、すべて条件付き) @@ -259,7 +280,7 @@ amadeus/ | 4.3 deployment-execution | `deployment-log.md`, `smoke-test-results.md`, `health-check-report.md` | | 4.4 observability-setup | `dashboards.md`, `alarms.md`, `slo-config.md`, `log-queries.md`, `tracing-config.md`, `anomaly-config.md` | | 4.5 incident-response | `runbooks.md`, `incident-plan.md`, `escalation-matrix.md` | -| 4.6 performance-validation | `load-test-plan.md`, `test-results.md`, `nfr-validation-matrix.md` | +| 4.6 performance-validation | `load-test-plan.md`, `load-test-results.md`, `nfr-validation-matrix.md` | | 4.7 feedback-optimization | `slo-report.md`, `cost-analysis.md`, `drift-report.md`, `feedback-loop.md` | --- diff --git a/docs/amadeus-files.md b/docs/amadeus-files.md index 5a2a4da660..87acf82f13 100644 --- a/docs/amadeus-files.md +++ b/docs/amadeus-files.md @@ -2,10 +2,11 @@ > Languages: **English** | [日本語](amadeus-files.ja.md) -Sources of truth: `amadeus-dlc/amadeus` v2 branch (commit `9b77786`, as of 2026-07) +Sources of truth: `amadeus-dlc/amadeus` (commit `f4d99c2c9`, as of 2026-08) - Official reference: `docs/guide/14-artifacts-reference.md` (directory tree and git policy) - Workspace layout: `docs/guide/03-spaces-and-intents.md` -- Exact file names: extracted from the `outputs:` frontmatter in all 32 stage files under `packages/framework/core/amadeus-common/stages/*/*.md` +- Generated trees: measured from `bun run dist` output (`dist/claude/.claude`, `dist/codex/.codex`, `dist/codex/.agents`) +- Exact file names: extracted from the `produces:` frontmatter in all 32 stage files under `packages/framework/core/amadeus-common/stages/*/*.md` --- @@ -13,6 +14,8 @@ Sources of truth: `amadeus-dlc/amadeus` v2 branch (commit `9b77786`, as of 2026- ``` .agents/ # Skill distribution consumed by Codex (sibling of .codex/) +├── rules/ # Codex entry point for AI-DLC rules +│ └── amadeus.md └── skills/ ├── amadeus/ # Orchestrator skill └── amadeus-/ # Stage runner / scope runner skill @@ -29,8 +32,10 @@ Sources of truth: `amadeus-dlc/amadeus` v2 branch (commit `9b77786`, as of 2026- │ ├── inception/ │ ├── construction/ │ └── operation/ -├── hooks/ # Claude Code hook implementations (framework hooks) +├── hooks/ # Claude Code hook implementations (framework hooks + Claude dispatcher) │ ├── amadeus-audit-logger.ts +│ ├── amadeus-dispatch.ts +│ ├── amadeus-log-subagent-start.ts │ ├── amadeus-log-subagent.ts │ ├── amadeus-mint-presence.ts │ ├── amadeus-plugin-compose.ts @@ -45,28 +50,35 @@ Sources of truth: `amadeus-dlc/amadeus` v2 branch (commit `9b77786`, as of 2026- ├── knowledge/ # Framework methodology knowledge (shared + per-agent) │ ├── amadeus-shared/ │ └── amadeus--agent/ +├── otel/ # OpenTelemetry provider layer (ships to every harness) ├── rules/ # Claude Code entry point for AI-DLC rules │ └── amadeus.md ├── scopes/ # Scope definitions such as amadeus-mvp │ └── amadeus-.md ├── sensors/ # Deterministic sensor definitions │ ├── amadeus-answer-evidence.md +│ ├── amadeus-event-registry-drift.md │ ├── amadeus-linter.md │ ├── amadeus-model-completeness.md │ ├── amadeus-required-sections.md +│ ├── amadeus-self-scope-consistency.md │ ├── amadeus-type-check.md │ └── amadeus-upstream-coverage.md ├── skills/ # Claude Code skills (orchestrator + stage runners) │ ├── amadeus/ │ └── amadeus-/ -├── tools/ # Deterministic Bun engine / CLI (26 files + data/) +├── tools/ # Deterministic Bun engine / CLI (amadeus-*.ts + data/) │ ├── amadeus-*.ts │ └── data/ +│ ├── harness.json │ ├── stage-graph.json +│ ├── stage-identities.json │ ├── scope-grid.json +│ ├── self-install-allowlist.ts │ ├── memory-seed/ │ ├── scaffold/ │ └── templates/ +├── vendor/ # Vendored OpenTelemetry API (ships to every harness) ├── CLAUDE.md # Claude Code onboarding instructions ├── CLAUDE.md.example ├── settings.json # Hook, statusline, and permission settings @@ -83,7 +95,9 @@ Sources of truth: `amadeus-dlc/amadeus` v2 branch (commit `9b77786`, as of 2026- │ └── stages/ ├── hooks/ # Codex hook implementations (shared framework hooks + Codex adapter) │ ├── amadeus-codex-adapter.ts +│ ├── amadeus-codex-hook-runtime.ts │ ├── amadeus-audit-logger.ts +│ ├── amadeus-log-subagent-start.ts │ ├── amadeus-log-subagent.ts │ ├── amadeus-mint-presence.ts │ ├── amadeus-plugin-compose.ts @@ -98,25 +112,32 @@ Sources of truth: `amadeus-dlc/amadeus` v2 branch (commit `9b77786`, as of 2026- ├── knowledge/ # Framework methodology knowledge (shared + per-agent) │ ├── amadeus-shared/ │ └── amadeus--agent/ +├── otel/ # OpenTelemetry provider layer (ships to every harness) ├── rules/ # Codex permission rules; separate from the AI-DLC memory layer │ └── default.rules ├── scopes/ # Scope definitions such as amadeus-mvp │ └── amadeus-.md ├── sensors/ # Deterministic sensor definitions │ ├── amadeus-answer-evidence.md +│ ├── amadeus-event-registry-drift.md │ ├── amadeus-linter.md │ ├── amadeus-model-completeness.md │ ├── amadeus-required-sections.md +│ ├── amadeus-self-scope-consistency.md │ ├── amadeus-type-check.md │ └── amadeus-upstream-coverage.md -├── tools/ # Deterministic Bun engine / CLI (26 files + data/) +├── tools/ # Deterministic Bun engine / CLI (amadeus-*.ts + data/) │ ├── amadeus-*.ts │ └── data/ +│ ├── harness.json │ ├── stage-graph.json +│ ├── stage-identities.json │ ├── scope-grid.json +│ ├── self-install-allowlist.ts │ ├── memory-seed/ │ ├── scaffold/ │ └── templates/ +├── vendor/ # Vendored OpenTelemetry API (ships to every harness) ├── config.toml # Codex project configuration (only when needed) ├── config.toml.example ├── hooks.json # Local active Codex hooks (per-clone, mutable, gitignored) @@ -247,7 +268,7 @@ Stages 3.1-3.5 repeat **per Unit of Work** and write to `construction/{unit-name | 3.3 nfr-design | `performance-design.md`, `security-design.md`, `scalability-design.md`, `reliability-design.md`, `logical-components.md` | Plan-dependent, per unit | | 3.4 infrastructure-design | `deployment-architecture.md`, `infrastructure-services.md`, `monitoring-design.md`, `cicd-pipeline.md`, and conditionally `shared-infrastructure.md` | Plan-dependent, per unit | | 3.5 code-generation | `code-generation-plan.md` (checkboxes + story tracking), `code-summary.md` (actual code goes to the code repository, not the record directory) | Always, per unit | -| 3.6 build-and-test | `build-instructions.md`, `unit-test-instructions.md`, `integration-test-instructions.md`, `performance-test-instructions.md`, `security-test-instructions.md`, `build-and-test-summary.md`, `test-results.md` | Always, after all units | +| 3.6 build-and-test | `build-instructions.md`, `unit-test-instructions.md`, `integration-test-instructions.md`, `performance-test-instructions.md`, `security-test-instructions.md`, `build-and-test-summary.md`, `build-test-results.md` | Always, after all units | | 3.7 ci-pipeline | `ci-config.md`, `quality-gates.md` | Conditional, after all units | ### 2.6 Operation (4.1-4.7, All Conditional) @@ -259,7 +280,7 @@ Stages 3.1-3.5 repeat **per Unit of Work** and write to `construction/{unit-name | 4.3 deployment-execution | `deployment-log.md`, `smoke-test-results.md`, `health-check-report.md` | | 4.4 observability-setup | `dashboards.md`, `alarms.md`, `slo-config.md`, `log-queries.md`, `tracing-config.md`, `anomaly-config.md` | | 4.5 incident-response | `runbooks.md`, `incident-plan.md`, `escalation-matrix.md` | -| 4.6 performance-validation | `load-test-plan.md`, `test-results.md`, `nfr-validation-matrix.md` | +| 4.6 performance-validation | `load-test-plan.md`, `load-test-results.md`, `nfr-validation-matrix.md` | | 4.7 feedback-optimization | `slo-report.md`, `cost-analysis.md`, `drift-report.md`, `feedback-loop.md` | --- diff --git a/docs/guide/05-scopes-and-depth.ja.md b/docs/guide/05-scopes-and-depth.ja.md index f5680a562b..852d0b087a 100644 --- a/docs/guide/05-scopes-and-depth.ja.md +++ b/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 ステージを含み、各ステージの承認ゲートで個々のステージをスキップできます。 diff --git a/docs/guide/05-scopes-and-depth.md b/docs/guide/05-scopes-and-depth.md index 19c666d955..ebcf36d4d8 100644 --- a/docs/guide/05-scopes-and-depth.md +++ b/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-.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. diff --git a/docs/guide/12-cli-commands.ja.md b/docs/guide/12-cli-commands.ja.md index bd3c904546..924336d897 100644 --- a/docs/guide/12-cli-commands.ja.md +++ b/docs/guide/12-cli-commands.ja.md @@ -24,6 +24,13 @@ | `/amadeus --status` | 読み取り専用のステータスサマリーを表示 | | `/amadeus --doctor` | セットアップのヘルスチェックを実行 | | `/amadeus --migrate [path]` | 本家 v2 ワークスペースをプレビューし、明示承認後に移行 | +| `/amadeus intent` | アクティブなスペース内の intent を一覧(読み取り専用。`--json` で構造化出力) | +| `/amadeus intent ` | アクティブな intent を切り替え | +| `/amadeus space` | スペースを一覧(読み取り専用。`--json` で構造化出力) | +| `/amadeus space ` | アクティブなスペース(チーム)を切り替え | +| `/amadeus space-create ` | フレームワークのベースラインから新しいスペース(チーム)を作成 | +| `/amadeus codekb-path` | リポジトリごとに決定的な codekb ディレクトリを出力(読み取り専用) | +| `/amadeus plugin ` | プラグイン CLI へ委譲(`status`、`compose`、`drop`、`doctor`、`install`) | | `/amadeus --stage ` | 特定のステージへジャンプ | | `/amadeus --stage --single` | ワークフローを進めずに 1 ステージを単独実行 | | `/amadeus --phase ` | フェーズの先頭へジャンプ | diff --git a/docs/guide/12-cli-commands.md b/docs/guide/12-cli-commands.md index cbd55fff03..59e9560796 100644 --- a/docs/guide/12-cli-commands.md +++ b/docs/guide/12-cli-commands.md @@ -24,6 +24,13 @@ All AI-DLC commands start with the orchestrator invocation. This chapter is a co | `/amadeus --status` | Display a read-only status summary | | `/amadeus --doctor` | Run a health check on your setup | | `/amadeus --migrate [path]` | Preview and, after explicit approval, migrate an upstream v2 workspace | +| `/amadeus intent` | List intents in the active space (read-only; `--json` for structured output) | +| `/amadeus intent ` | Switch the active intent | +| `/amadeus space` | List spaces (read-only; `--json` for structured output) | +| `/amadeus space ` | Switch the active space (team) | +| `/amadeus space-create ` | Create a new space (team) seeded from the framework baseline | +| `/amadeus codekb-path` | Print the deterministic per-repo codekb directory (read-only) | +| `/amadeus plugin ` | Delegate to the plugin CLI (`status`, `compose`, `drop`, `doctor`, `install`) | | `/amadeus --stage ` | Jump to a specific stage | | `/amadeus --stage --single` | Run one stage in isolation, without advancing your workflow | | `/amadeus --phase ` | Jump to the start of a phase | diff --git a/docs/guide/17-skills.ja.md b/docs/guide/17-skills.ja.md index d7551ae44b..f49b79cb45 100644 --- a/docs/guide/17-skills.ja.md +++ b/docs/guide/17-skills.ja.md @@ -38,6 +38,10 @@ `/amadeus-plugin`。最初の4つは読み取り専用のビューまたはインタビューです。 `/amadeus-mirror` と `/amadeus-plugin` は最初に診断(`status`)し、その後 ユーザーが選択した1操作だけを実行できます。 +- **ユーティリティスキル** — `/amadeus-compose`(適応的コンポーザーを強制し、 + タスクに合わせた EXECUTE/SKIP プランを提案)、`/amadeus-election`(選挙 CLI の + typed directive ループでチーム選挙を駆動)、`/amadeus-upstream-sync`(本家 + AI-DLC v2 タグとの同期を計画)。 ランナーが行うことはすべてフラグ付きの `/amadeus` から到達可能です。ランナーは パッケージングです — `/amadeus-fix` とタイプして `/` メニューに現れるのは良い @@ -116,8 +120,9 @@ basename だけを受け入れ、単一引数として渡します。basename ``` **ランナーを同梱するのは 4 つのスコープだけ** — トラフィックの多いものです。 -フレームワークは合計 10 個のスコープを定義しています([スコープ、深さ、テスト戦略](05-scopes-and-depth.ja.md) を参照)。 -他のすべて — `chore`、`enterprise`、`infra`、`poc`、`refactor`、`workshop` — は常に +フレームワークは合計 15 個のスコープを定義しています([スコープ、深さ、テスト戦略](05-scopes-and-depth.ja.md) を参照)。 +他のすべて — `chore`、`enterprise`、`infra`、`installer-distribution`、`poc`、`refactor`、 +`self-document`、`self-feature`、`self-fix`、`self-refactor`、`workshop` — は常に オーケストレーター経由で到達可能です: ``` @@ -125,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 ` を使ってください。 @@ -187,6 +194,7 @@ basename だけを受け入れ、単一引数として渡します。basename | Init ラッパー | `/amadeus-init` | 最初の intent を誕生させる(Initialization を実行) | 新規ワークスペースでの `/amadeus` | | セッションビュー | `/amadeus-session-cost`、`/amadeus-replay`、`/amadeus-outcomes-pack` | 読み取り専用のワークフローレポート | [セッション管理](11-session-management.ja.md) を参照 | | Grilling インタビュー | `/amadeus-grilling` | プランや設計についての読み取り専用の一問一答インタビュー | [インタラクションモード](07-interaction-modes.ja.md) を参照 | +| ユーティリティスキル | `/amadeus-compose`、`/amadeus-election`、`/amadeus-upstream-sync` | 合わせたプランの提案、チーム選挙の駆動、本家同期の計画 | 最初のものは `/amadeus compose ""` | ライフサイクル内の実行可能なステージごとにステージランナーが 1 つあります。全体の セットを見るには、スキルディレクトリを一覧してください: @@ -246,7 +254,7 @@ bun .claude/tools/amadeus-runner-gen.ts scopes --check # スコープランナ ``` # フルワークフロー /amadeus スコープを検出し、すべてを実行 -/amadeus --scope enterprise 10 スコープのいずれか +/amadeus --scope enterprise 名前付きスコープのいずれか # スコープランナー(トラフィックの多い 4 つの入口) /amadeus-fix · /amadeus-feature · /amadeus-mvp · /amadeus-security-patch diff --git a/docs/guide/17-skills.md b/docs/guide/17-skills.md index 01de5fea48..b6e2e81f19 100644 --- a/docs/guide/17-skills.md +++ b/docs/guide/17-skills.md @@ -22,6 +22,7 @@ Every command this implementation ships is a skill under `.claude/skills/`. They - **Stage-runners** — `/amadeus-application-design`, `/amadeus-code-generation`, and 27 more. Run one stage in isolation, never touching your main workflow. - **`/amadeus-init`** — birth the first intent (run the whole Initialization phase) in one step; opt-in packaging over the engine's auto-birth. - **Session skills** — `/amadeus-session-cost`, `/amadeus-replay`, `/amadeus-outcomes-pack`, `/amadeus-grilling`, `/amadeus-mirror`, `/amadeus-plugin`. The first four are read-only views or interviews. `/amadeus-mirror` and `/amadeus-plugin` diagnose first (`status`), then can run one user-selected action. +- **Utility skills** — `/amadeus-compose` (force the adaptive composer to propose a tailored EXECUTE/SKIP plan), `/amadeus-election` (drive a team election through the election CLI's typed directive loop), `/amadeus-upstream-sync` (plan synchronization with official upstream AI-DLC v2 tags). Everything a runner does is reachable from `/amadeus` with a flag. The runners are packaging — typing `/amadeus-fix` and seeing it in your `/` menu is good ergonomics, nothing more. Delete every runner and the shortcuts go; the capability stays, reachable through `/amadeus` flags. @@ -101,13 +102,15 @@ You can pass a description and flags straight through, exactly as you would to ` /amadeus-feature --status ``` -**Only four scopes ship a runner** — the high-traffic ones. The framework defines ten scopes total (see [Scopes, Depth, and Test Strategy](05-scopes-and-depth.md)); every other one — `chore`, `enterprise`, `infra`, `poc`, `refactor`, `workshop` — is always reachable through the orchestrator: +**Only four scopes ship a runner** — the high-traffic ones. The framework defines fifteen scopes total (see [Scopes, Depth, and Test Strategy](05-scopes-and-depth.md)); every other one — `chore`, `enterprise`, `infra`, `installer-distribution`, `poc`, `refactor`, `self-document`, `self-feature`, `self-fix`, `self-refactor`, `workshop` — is always reachable through the orchestrator: ``` /amadeus --scope enterprise /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 `. --- @@ -157,6 +160,7 @@ The three bootstrap **initialization** stages ship no stage-runner — birthing | Init wrapper | `/amadeus-init` | Birth the first intent (run Initialization) | `/amadeus` on a fresh workspace | | Session views | `/amadeus-session-cost`, `/amadeus-replay`, `/amadeus-outcomes-pack` | Read-only workflow reports | see [Session Management](11-session-management.md) | | Grilling interview | `/amadeus-grilling` | Read-only one-question-at-a-time interview about a plan or design | see [Interaction Modes](07-interaction-modes.md) | +| Utility skills | `/amadeus-compose`, `/amadeus-election`, `/amadeus-upstream-sync` | Compose a tailored plan, drive a team election, plan an upstream sync | `/amadeus compose ""` for the first | There's one stage-runner for every runnable stage in the lifecycle. To see the full set, list your skills directory: @@ -200,7 +204,7 @@ For the mechanics of writing a stage file, see [Customization](13-customization. ``` # Full workflow /amadeus detect scope, run everything -/amadeus --scope enterprise any of the 10 scopes +/amadeus --scope enterprise any named scope # Scope-runners (the 4 high-traffic doors) /amadeus-fix · /amadeus-feature · /amadeus-mvp · /amadeus-security-patch diff --git a/docs/guide/19-plugins.ja.md b/docs/guide/19-plugins.ja.md index be0a4f247a..c0984d9af4 100644 --- a/docs/guide/19-plugins.ja.md +++ b/docs/guide/19-plugins.ja.md @@ -10,8 +10,8 @@ この章は利用者向けリファレンスであり、オーサリングガイドです。プラグインシステムが 現在サポートする面、そのコマンドライン面、セッション起動時にプラグインがホストへ自動 -compose される仕組み、利用者に見える安全契約、ローカルでの検証手順、そして 7 つの -パッケージハーネス面と 5 つのセルフインストール面の違いを記述します。これはいかなる +compose される仕組み、利用者に見える安全契約、ローカルでの検証手順、そして +パッケージハーネス面とセルフインストール面の違いを記述します。これはいかなる 上流 README のコピーでもありません — 以下のパス・コマンド・失敗契約はすべて Amadeus のものです。 @@ -65,7 +65,7 @@ plugins/example/ 1. **オーサリング** — `plugins//plugin.json` と参照ファイルを書きます。 2. **投影** — パッケージャが `plugins/` を discover し、各ソースを構造的に検証 (マニフェスト存在・identity 一意・プラグイン自身のサブツリーを逸脱するパスなし) - し、各プラグインを 7 つのパッケージハーネスツリーとハーネス中立バンドルへ投影 + し、各プラグインを各パッケージハーネスツリーとハーネス中立バンドルへ投影 します。プラグインが 0 件のとき、出力はプラグイン非対応ビルドと byte-identical です。 3. **inspect** — 合成エンジンが discover 済みプラグインをホストスナップショットと @@ -120,7 +120,7 @@ verb は次のとおりです。 読み戻すルートと同一なので、install・compose・discovery が乖離することはありません。 `--project-root ` はこれを上書きして別のホストを対象にします — CLI が存在する場所 以外のホストへ compose する手段で、パッケージされるがセルフインストールされない -`kiro` / `kiro-ide` 面では常に必要です。 +`kiro` / `kiro-ide` / `pi` 面では常に必要です。 引数処理は fail-closed で、いかなる変更よりも **前** に行われます: 未知 verb・未知 フラグ・余剰引数は usage を stderr へ出して exit `2` で終わり、ホストには一切触れません。 @@ -137,8 +137,8 @@ compose を配線しています。`--if-stale` 高速路により、合成レ 起動レイテンシを増やしません。フックの失敗は stderr 警告 1 行と exit 0 であり — プラグインの問題がセッションをブロックすることはありません。 -7 つのパッケージ面すべてがこのトリガーを配線します。Kiro CLI と Kiro IDE は同じ -`.kiro` host tree を共有するため、7 面は 6 個の host directory を対象にします。 +8 つのパッケージ面すべてがこのトリガーを配線します。Kiro CLI と Kiro IDE は同じ +`.kiro` host tree を共有するため、8 面は 7 個の host directory を対象にします。 | 面 | session-start トリガー | 自動 compose | | --- | --- | --- | @@ -149,6 +149,7 @@ compose を配線しています。`--if-stale` 高速路により、合成レ | `kiro` | `agentSpawn` | 配線あり | | `kiro-ide` | `promptSubmit`(`--if-stale` で冪等) | 配線あり | | `opencode` | JavaScript plugin の `session.created` event | 配線あり | +| `pi` | extension の `session_start` event | 配線あり | OpenCode は shell hook ではなく公式 JavaScript/TypeScript plugin event を使います。既存の `.opencode/plugins/amadeus-opencode-plugin.ts` が `session.created` を処理し、`.opencode` @@ -186,7 +187,7 @@ OpenCode は shell hook ではなく公式 JavaScript/TypeScript plugin event - **`native-manifest`**(`claude`)— ホストのプラグインマーケットプレイス経由で `.claude-plugin/plugin.json` を使ってインストール。自動 compose は `hooks/hooks.json` から走ります。 -- **`folder-drop-auto`**(`codex`・`cursor`・`kimi`・`kiro`・`kiro-ide`)— バンドルの +- **`folder-drop-auto`**(`codex`・`cursor`・`kimi`・`kiro`・`kiro-ide`・`pi`)— バンドルの `plugins//` を、プロジェクトルート配下の `<ハーネスディレクトリ>/.amadeus-plugin-src//`(Codex なら `.codex/.amadeus-plugin-src//`)へコピー。ここが `compose` の走査先であり、 @@ -279,7 +280,7 @@ spec が drift したことを知らせ、*あなた* がチェック再実行 検証はローカルかつ一時的です — プラグインを試すためにコミット済みツリーを変更する ことはありません。リファレンスライフサイクルテストがモデルです。canonical ソースを 使い捨ての一時ワークスペースへコピーし、パッケージャのソース/出力ルートをそこへ -リダイレクトし(`AMADEUS_PLUGINS_ROOT` / `AMADEUS_DIST_ROOT`)、7 面すべてへ投影し、 +リダイレクトし(`AMADEUS_PLUGINS_ROOT` / `AMADEUS_DIST_ROOT`)、全面へ投影し、 一時ホストへ compose し、doctor を実行し、drop します。宣言物だけが生成・検出・除去 され、tracked tree に一時ファイルが 1 つも残らないことを assert します。 @@ -295,11 +296,50 @@ bun test tests/integration/t254-reference-plugin-lifecycle.test.ts --- -## 7 つのパッケージ面、5 つのセルフインストール面 +## import する全モジュールを宣言する -パッケージャは各プラグインを **7 つ** のハーネス面へ投影します: `claude`・`codex`・ -`cursor`・`kiro`・`kiro-ide`・`opencode`・`kimi`。セルフインストール(ハーネスを +compose されたプラグインは、`plugin.json` が宣言したファイルだけを運びます。したがって +宣言済みツールが import しているのに `tools` へ載せ忘れたヘルパーモジュールは、単なる +記載漏れではなく、compose 後の全ホストにおける import 欠落です。ファイルがディスク上に +そのまま在る自分の作業ツリーではロードでき、実際にインストールされた先で失敗します。 + +パッケージャはこれを **import-closure guard** で塞ぎます。manifest が宣言する各ツールを +起点に *相対* import(`./x.ts`・`../y.ts`)の推移閉包を辿り、到達した全モジュールが +`plugin.json` に宣言され、かつプラグイン自身のソースとして実在することを要求します。 +`node:crypto` のような bare specifier はランタイムがプラグインツリーの外から解決するため +対象外で、絶対指定は境界違反として報告されます。 + +guard は投影の一部として走るため、壊れた面を出荷する代わりにビルドが失敗します。 +allowlist も skip フラグもありません — モジュールは宣言され所有されることで通り、 +そうでなければ通りません。読めない参照は閉包から取り除かれるのではなく failure として +列挙されます。これが、import パスの typo が検査対象集合を無言で縮めることを防ぎます。 + +失敗は違反参照ごとに1行、プラグイン名を前置して出力されます。最初の1件で止まらず、 +修復すべき集合が一度に列挙されます。 + +``` +MISSING from formal-model-check plugin.json: plugins/formal-model-check/tools/helper.ts +MISSING from formal-model-check owned sources: plugins/formal-model-check/tools/helper.ts +UNREADABLE import in formal-model-check: plugins/formal-model-check/tools/typo.ts +``` + +3つの異なる修復として読みます。`MISSING from … plugin.json` は、ファイルはプラグイン内に +実在するが manifest が運んでいない — `tools` へ追加します。`MISSING from … owned sources` +は、manifest が名指すパスに対応するファイルがプラグイン内に無い状態です。 +`UNREADABLE import` は参照自体が解決できなかった場合で、ファイル不在・不正なパス・ +実体がリポジトリ外へ出る symlink のいずれかです。 + +guard の実体は `scripts/import-closure-guard.ts` にあります。内部構造とテスト配置は +[コントリビュート](../reference/11-contributing.ja.md#プラグイン-import-closure-guard) +を参照してください。 + +--- + +## 8 つのパッケージ面、5 つのセルフインストール面 + +パッケージャは各プラグインを **8 つ** のハーネス面へ投影します: `claude`・`codex`・ +`cursor`・`kiro`・`kiro-ide`・`opencode`・`kimi`・`pi`。セルフインストール(ハーネスを プロジェクトルートへ反映すること)は **閉じた 5 面** のままです: `claude`・`codex`・ -`cursor`・`opencode`・`kimi`。`kiro` と `kiro-ide` はパッケージされますがプロジェクト +`cursor`・`opencode`・`kimi`。`kiro`・`kiro-ide`・`pi` はパッケージされますがプロジェクト ルートへは決して昇格しません。2 つのマトリクスは別々の期待集合に対して検証され、一方が -他方の代替に使われることも、5 面が 7 面へ広げられることもありません。 +他方の代替に使われることも、5 面がパッケージ面の集合へ広げられることもありません。 diff --git a/docs/guide/19-plugins.md b/docs/guide/19-plugins.md index 9197436918..0d5b9baa59 100644 --- a/docs/guide/19-plugins.md +++ b/docs/guide/19-plugins.md @@ -12,8 +12,8 @@ anything the workspace already owns. This chapter is the user-facing reference and the authoring guide. It describes what the plugin system supports today, its command-line surface, how a plugin is composed into a host automatically at session start, what the safety contract -guarantees, how to verify a plugin locally, and how the seven packaged harness -faces differ from the five self-install faces. It is not a copy of any upstream +guarantees, how to verify a plugin locally, and how the packaged harness +faces differ from the self-install faces. It is not a copy of any upstream README — every path, command, and failure contract below is the Amadeus one. The worked example is the reference plugin `test-pro`, kept as authoring source @@ -67,8 +67,8 @@ in-prose `rules/` paths rewritten. JSON and TypeScript are copied verbatim. 1. **Author** — write `plugins//plugin.json` and its referenced files. 2. **Project** — the packager discovers `plugins/`, validates each source structurally (a manifest is present, identities are unique, no path escapes - the plugin's own subtree), and projects every plugin into the seven packaged - harness trees plus a harness-neutral bundle. With no plugins present, the + the plugin's own subtree), and projects every plugin into each packaged + harness tree plus a harness-neutral bundle. With no plugins present, the output is byte-identical to a plugin-free build. 3. **Inspect** — the composition engine checks a discovered plugin against a host snapshot and collects *every* problem (same-name stage, malformed manifest, @@ -126,8 +126,8 @@ is installed in** — `bun .codex/tools/amadeus-plugin.ts compose` composes into `.codex/` from anywhere. That is the same root the engine reads composed plugin stages back from, so install, compose, and discovery cannot drift apart. `--project-root ` overrides it to target another host — it is how you compose -into a host that is not where the CLI lives (the `kiro` and `kiro-ide` faces, -which are packaged but never self-installed, always need it). +into a host that is not where the CLI lives (the `kiro`, `kiro-ide`, and `pi` +faces, which are packaged but never self-installed, always need it). Argument handling is fail-closed and happens **before** any mutation: an unknown verb, an unknown flag, or a surplus argument prints usage on stderr and exits `2` @@ -146,8 +146,8 @@ pays only a few `existsSync` probes and returns without recomposing, so the hook adds no startup latency in the common case. Any hook failure is a single stderr warning and a zero exit — a plugin problem never blocks the session. -All seven packaged faces wire this trigger. Kiro CLI and Kiro IDE share one -`.kiro` host tree, so the seven faces cover six host directories: +All eight packaged faces wire this trigger. Kiro CLI and Kiro IDE share one +`.kiro` host tree, so the eight faces cover seven host directories: | Face | Session-start trigger | Auto-compose | | --- | --- | --- | @@ -158,6 +158,7 @@ All seven packaged faces wire this trigger. Kiro CLI and Kiro IDE share one | `kiro` | `agentSpawn` | wired | | `kiro-ide` | `promptSubmit` (idempotent via `--if-stale`) | wired | | `opencode` | JavaScript plugin `session.created` event | wired | +| `pi` | extension `session_start` event | wired | OpenCode uses its official JavaScript/TypeScript plugin event rather than a shell hook. The existing `.opencode/plugins/amadeus-opencode-plugin.ts` handles @@ -191,13 +192,13 @@ or silently dropped — it renders as an `unknown` row that fails the check. ## Installing a plugin into a host -The packager emits a per-face **install bundle** for every one of the seven faces, +The packager emits a per-face **install bundle** for every one of the eight faces, alongside a top-level `INSTALL.md` whose steps are dispatched on the face's host class: - **`native-manifest`** (`claude`) — install through the host plugin marketplace using `.claude-plugin/plugin.json`; auto-compose runs from `hooks/hooks.json`. -- **`folder-drop-auto`** (`codex`, `cursor`, `kimi`, `kiro`, `kiro-ide`) — copy the +- **`folder-drop-auto`** (`codex`, `cursor`, `kimi`, `kiro`, `kiro-ide`, `pi`) — copy the bundle's `plugins//` into `/.amadeus-plugin-src//` under your project root (`.codex/.amadeus-plugin-src//` for Codex, and so on) — the harness-rooted directory `compose` scans, which is also the root the engine @@ -295,8 +296,8 @@ the hash matches, the advisory is silent. Verification is local and temporary — you never mutate the committed tree to try a plugin out. The reference lifecycle test is the model: it copies the canonical source into a throwaway temp workspace, redirects the packager's source and output -roots there (`AMADEUS_PLUGINS_ROOT` / `AMADEUS_DIST_ROOT`), projects into all seven -faces, composes into a temp host, runs the doctor, and drops — asserting that only +roots there (`AMADEUS_PLUGINS_ROOT` / `AMADEUS_DIST_ROOT`), projects into every +face, composes into a temp host, runs the doctor, and drops — asserting that only the declared artifacts are created, detected, and removed and that no temporary file survives in the tracked tree. @@ -312,12 +313,57 @@ clean afterwards. --- -## Seven packaged faces, five self-install faces +## Declaring every module you import -The packager projects every plugin into **seven** harness faces: `claude`, -`codex`, `cursor`, `kiro`, `kiro-ide`, `opencode`, and `kimi`. Self-install — the -reflection of a harness into the project root — stays the **closed five**: -`claude`, `codex`, `cursor`, `opencode`, and `kimi`. `kiro` and `kiro-ide` are -packaged but never promoted to the project root. The two matrices are verified -against separate expected sets; one is never used as a stand-in for the other, and -the five is never widened to seven. +A composed plugin carries exactly the files its `plugin.json` declares. So a +helper module that your declared tool imports, but that you forgot to list in +`tools`, is not a stylistic omission — it is a missing import in every composed +host. The plugin loads in your working tree, where the file is simply there on +disk, and fails wherever it is actually installed. + +The packager closes this with the **import-closure guard**. Starting from each +tool your manifest declares, it walks the transitive closure of *relative* +imports (`./x.ts`, `../y.ts`) and requires every module it reaches to be both +declared in `plugin.json` and present among your plugin's own source files. Bare +specifiers like `node:crypto` are resolved by the runtime from outside the plugin +tree and are out of scope; an absolute specifier is a boundary violation and is +reported as such. + +The guard runs as part of the projection, so a build fails rather than shipping +a broken face. It has no allowlist and no skip flag — a module passes by being +declared and owned, or not at all. A reference it cannot read is enumerated as a +failure instead of being dropped from the closure, which is what keeps a typo in +an import path from quietly shrinking the set that gets checked. + +Failures print one line per offending reference, prefixed with your plugin's +name, and the whole repair set is listed at once rather than stopping at the +first offender: + +``` +MISSING from formal-model-check plugin.json: plugins/formal-model-check/tools/helper.ts +MISSING from formal-model-check owned sources: plugins/formal-model-check/tools/helper.ts +UNREADABLE import in formal-model-check: plugins/formal-model-check/tools/typo.ts +``` + +Read them as three distinct repairs. `MISSING from … plugin.json` means the file +exists in your plugin but the manifest does not carry it — add it to `tools`. +`MISSING from … owned sources` means the manifest names a path with no file +behind it inside the plugin. `UNREADABLE import` means the reference could not be +resolved at all: an absent file, a bad path, or a symlink whose real target +leaves the repository. + +The guard lives at `scripts/import-closure-guard.ts`; its internals and test +layout are described in +[Contributing](../reference/11-contributing.md#the-plugin-import-closure-guard). + +--- + +## Eight packaged faces, five self-install faces + +The packager projects every plugin into **eight** harness faces: `claude`, +`codex`, `cursor`, `kiro`, `kiro-ide`, `opencode`, `kimi`, and `pi`. +Self-install — the reflection of a harness into the project root — stays the +**closed five**: `claude`, `codex`, `cursor`, `opencode`, and `kimi`. `kiro`, +`kiro-ide`, and `pi` are packaged but never promoted to the project root. The two +matrices are verified against separate expected sets; one is never used as a +stand-in for the other, and the five is never widened to the packaged set. diff --git a/docs/guide/harnesses/codex-cli.ja.md b/docs/guide/harnesses/codex-cli.ja.md index 9a22c89d27..b856d72ed8 100644 --- a/docs/guide/harnesses/codex-cli.ja.md +++ b/docs/guide/harnesses/codex-cli.ja.md @@ -352,7 +352,7 @@ bridge が実際に起動し、再起動後も動くことまでは証明しま オーケストレーターは `$amadeus`(または `/skills` → amadeus)にスコープや説明を 続けて起動します — Claude ハーネスと同じコマンドです(`$amadeus --status`、 `$amadeus --help`、…)。ステージランナーは明示指定のみです: -`$amadeus-application-design`、`$amadeus-fix` など(37 個のランナー説明が +`$amadeus-application-design`、`$amadeus-code-generation` など(ランナーの説明が インデックスを汚染しないよう、暗黙のスキルマッチングから除外されています)。 ## Claude Code との相違点 diff --git a/docs/guide/harnesses/codex-cli.md b/docs/guide/harnesses/codex-cli.md index 869cbc3df0..2eb5178f0c 100644 --- a/docs/guide/harnesses/codex-cli.md +++ b/docs/guide/harnesses/codex-cli.md @@ -359,8 +359,8 @@ or an unperformed check leaves the monitor-bridge change incomplete. Invoke the orchestrator with `$amadeus` (or `/skills` → amadeus) followed by a scope or description — same commands as the Claude harness (`$amadeus --status`, `$amadeus --help`, …). Stage runners are explicit-only: -`$amadeus-application-design`, `$amadeus-fix`, etc. (they are excluded from -implicit skill matching so 37 runner descriptions don't pollute the index). +`$amadeus-application-design`, `$amadeus-code-generation`, etc. (they are excluded from +implicit skill matching so the runner descriptions don't pollute the index). ## Harness differences vs Claude Code diff --git a/docs/harness-engineering/04-scopes.ja.md b/docs/harness-engineering/04-scopes.ja.md index dddc627ec3..dc51fb2d56 100644 --- a/docs/harness-engineering/04-scopes.ja.md +++ b/docs/harness-engineering/04-scopes.ja.md @@ -2,11 +2,11 @@ > 言語: [English](04-scopes.md) | **日本語** -スコープは、ある種類の作業に対してフレームワークの32ステージのうち*どれ*を実行し、どれを実行しないかを決めるダイヤルです。fix には市場調査やデプロイパイプラインは不要ですし、規制対象のエンタープライズ機能にはそのすべてが必要になります。毎回ユーザーにステージを手作業で選ばせるのではなく、AI-DLC は10個の名前付きスコープを同梱しています。各スコープは全ステージ集合に対する EXECUTE/SKIP の判定を丁寧にキュレーションしたもので、デフォルトの深さ(depth)とテスト戦略(test strategy)が対になっています。スコープを選べば、あとは連鎖的に決まります。 +スコープは、ある種類の作業に対してフレームワークの32ステージのうち*どれ*を実行し、どれを実行しないかを決めるダイヤルです。fix には市場調査やデプロイパイプラインは不要ですし、規制対象のエンタープライズ機能にはそのすべてが必要になります。毎回ユーザーにステージを手作業で選ばせるのではなく、AI-DLC は名前付きスコープのカタログを同梱しています。各スコープは全ステージ集合に対する EXECUTE/SKIP の判定を丁寧にキュレーションしたもので、デフォルトの深さ(depth)とテスト戦略(test strategy)が対になっています。スコープを選べば、あとは連鎖的に決まります。 ハーネスエンジニアにとって、スコープは他のすべてのプリミティブと同じ方法で — ファイルとして — 記述される純粋なデータです。スコープは2つの半分から成ります。1つは `packages/framework/core/scopes/amadeus-.md` ファイル(そのアイデンティティ — 名前、深さ、キーワード、説明)、もう1つはステージごとのメンバーシップタグ(各ステージのフロントマターの `scopes:` リストが、そのステージが実行されるスコープを列挙する)です。スコープの追加やチューニングに TypeScript は不要です。この章ではワークフローを追っていきます。スコープが何で構成されるか、チームスコープをどう追加するか、既存のものをどうチューニングするか、そしてツールが何を検証してくれて何をあなたに委ねるか。 -ユースケースとユーザーが読むルーティングテーブルを含む10スコープの完全なカタログについては、ユーザーガイドの [Scopes, Depth, and Test Strategy](../guide/05-scopes-and-depth.ja.md) を参照してください。この章は同じデータを記述する(オーサリング)側です。 +ユースケースとユーザーが読むルーティングテーブルを含む全スコープの完全なカタログについては、ユーザーガイドの [Scopes, Depth, and Test Strategy](../guide/05-scopes-and-depth.ja.md) を参照してください。この章は同じデータを記述する(オーサリング)側です。 --- @@ -39,7 +39,7 @@ Prose intent: why these stages, why skip those. | `keywords` | No | `/amadeus ` の自動検出のための自然言語トリガー。空リストはオプトアウト。 | | `description` | No | `/amadeus --help` に表示される1行説明。(SKILL.md のコンパイル済みスコープテーブルは Scope / Depth / TestStrategy / EXECUTE / Total のみを表示し、description は含めない。) | -プロジェクトローカルなスコープ名には、フレームワーク接頭辞を重ねず、その役割を表す名前を使います。Amadeus の自己開発では `self-feature`、`self-fix`、`self-refactor`、`self-document` を使用し、ファイル名は `amadeus-self-fix.md` のようにします。`amadeus-amadeus-*.md` という二重接頭辞は使用しません。 +プロジェクトローカルなスコープ名には、フレームワーク接頭辞を重ねず、その役割を表す名前を使います。Amadeus の自己開発では `self-feature`、`self-fix`、`self-refactor`、`self-document` を使用し、ファイル名は `amadeus-self-fix.md` のようにします。`amadeus-amadeus-*.md` という二重接頭辞は使用しません。これら4つのスコープがそれぞれ何のためのもので、どう使い分けるかは、ユーザーガイドの[自己開発スコープ](../guide/05-scopes-and-depth.ja.md#自己開発スコープself-) を参照してください。 **2. メンバーシップタグ — 各ステージの `scopes:` フロントマター。** ステージは、`packages/framework/core/amadeus-common/stages//.md` にある自身のフロントマターで、自分が実行されるスコープを列挙します。 @@ -62,7 +62,7 @@ scopes: スコープとステージは反対側の端から互いを指し示しており、両方向を同時に把握しておくと役立ちます。 -**ステージ**は自身のアイデンティティ — そのフェーズ、リードエージェント、消費・生成する成果物、そして今や自分が実行されるスコープ(その `scopes:` リスト) — を宣言します。**スコープ**はそれ自身の `.md` ファイルでアイデンティティ — 名前、深さ、キーワード、説明 — を宣言し、内部にステージごとのメンバーシップは持ちません。メンバーシップはステージ側に置かれます。両者を結び付けるのはスコープ名です。新しいステージを追加するとき(参照: [Adding a Stage](02-adding-a-stage.ja.md))、スコープのメンバーシップは*そのステージ上*に置きます — その `scopes:` リストが、それを実行すべきすべてのスコープを列挙します。どのスコープも列挙しないステージは、どこでも `SKIP` です。コンパイル時の転置がこれらステージごとのリストをグリッドに変えるため、メンバーシップは10個の別々のスコープブロックで再宣言するのではなく、ステージ上で一度だけ記述されます。 +**ステージ**は自身のアイデンティティ — そのフェーズ、リードエージェント、消費・生成する成果物、そして今や自分が実行されるスコープ(その `scopes:` リスト) — を宣言します。**スコープ**はそれ自身の `.md` ファイルでアイデンティティ — 名前、深さ、キーワード、説明 — を宣言し、内部にステージごとのメンバーシップは持ちません。メンバーシップはステージ側に置かれます。両者を結び付けるのはスコープ名です。新しいステージを追加するとき(参照: [Adding a Stage](02-adding-a-stage.ja.md))、スコープのメンバーシップは*そのステージ上*に置きます — その `scopes:` リストが、それを実行すべきすべてのスコープを列挙します。どのスコープも列挙しないステージは、どこでも `SKIP` です。コンパイル時の転置がこれらステージごとのリストをグリッドに変えるため、メンバーシップはスコープごとの別々のブロックで再宣言するのではなく、ステージ上で一度だけ記述されます。 この分離は、このガイドの他の部分が依拠しているのと同じ「データ対コード」の線です(参照: [Harness Engineer Guide](00-overview.ja.md))。スコープファイルは*アイデンティティ*についてのデータ、ステージの `scopes:` リストは*メンバーシップ*についてのデータ、そしてコンパイル済みグリッドはその2つの転置です。 @@ -115,7 +115,7 @@ scopes: いずれの場合も、上記の手順3の「再コンパイルと doctor」のペアが適用されます。編集は小さく、検証は同じです。 -レイヤリングに関する注意: 同梱スコープをチューニングすることは、フレームワーク同梱ファイルを直接編集することを意味します — ステージの `scopes:` タグや、同梱の `packages/framework/core/scopes/amadeus-*.md` です。異なるデフォルトを望むフォークにとってこれは正当ですが、`amadeus-` の系譜を担うファイルを変更していること、そしてフレームワークのアップグレードがそれらを整合させたがるかもしれないことに注意してください。他の全員が依拠するデフォルトに触れずにチーム固有の振る舞いが欲しい場合は、同梱の10個と並べて完全に新規のスコープファイルを追加するのがよりクリーンな道です。 +レイヤリングに関する注意: 同梱スコープをチューニングすることは、フレームワーク同梱ファイルを直接編集することを意味します — ステージの `scopes:` タグや、同梱の `packages/framework/core/scopes/amadeus-*.md` です。異なるデフォルトを望むフォークにとってこれは正当ですが、`amadeus-` の系譜を担うファイルを変更していること、そしてフレームワークのアップグレードがそれらを整合させたがるかもしれないことに注意してください。他の全員が依拠するデフォルトに触れずにチーム固有の振る舞いが欲しい場合は、同梱のスコープと並べて完全に新規のスコープファイルを追加するのがよりクリーンな道です。 --- diff --git a/docs/harness-engineering/04-scopes.md b/docs/harness-engineering/04-scopes.md index e3e2c2db30..8f3ad934d4 100644 --- a/docs/harness-engineering/04-scopes.md +++ b/docs/harness-engineering/04-scopes.md @@ -2,11 +2,11 @@ > Languages: **English** | [日本語](04-scopes.ja.md) -A scope is the dial that decides *which* of the framework's 32 stages run for a given kind of work, and which sit out. A fix doesn't need market research or a deployment pipeline; a regulated enterprise feature needs all of it. Rather than asking the user to hand-pick stages every time, AI-DLC ships ten named scopes — each one a curated EXECUTE/SKIP verdict over the full stage set, paired with a default depth and test strategy. Pick the scope and the rest cascades. +A scope is the dial that decides *which* of the framework's 32 stages run for a given kind of work, and which sit out. A fix doesn't need market research or a deployment pipeline; a regulated enterprise feature needs all of it. Rather than asking the user to hand-pick stages every time, AI-DLC ships a catalog of named scopes — each one a curated EXECUTE/SKIP verdict over the full stage set, paired with a default depth and test strategy. Pick the scope and the rest cascades. For a harness engineer, a scope is pure data, authored the same way every other primitive is — as a file. It is two halves: one `packages/framework/core/scopes/amadeus-.md` file (its identity — name, depth, keywords, description) plus a per-stage membership tag (each stage's frontmatter `scopes:` list naming the scopes it runs under). Adding or tuning a scope requires no TypeScript. This chapter walks the workflow: what a scope is made of, how to add a team scope, how to tune an existing one, and what the tooling checks for you versus what it leaves to you. -For the full ten-scope catalog with use cases and the routing table users read, see [Scopes, Depth, and Test Strategy](../guide/05-scopes-and-depth.md) in the User Guide. This chapter is the authoring side of that same data. +For the full scope catalog with use cases and the routing table users read, see [Scopes, Depth, and Test Strategy](../guide/05-scopes-and-depth.md) in the User Guide. This chapter is the authoring side of that same data. --- @@ -42,7 +42,10 @@ The frontmatter fields divide into one required field and three optional knobs: Project-local scope names should describe their role without repeating the framework prefix. Amadeus self-development therefore uses `self-feature`, `self-fix`, `self-refactor`, and `self-document`, producing filenames such as -`amadeus-self-fix.md`; do not use the doubled `amadeus-amadeus-*.md` form. +`amadeus-self-fix.md`; do not use the doubled `amadeus-amadeus-*.md` form. For +what each of those four scopes is for and when to select it, see +[Self-development scopes](../guide/05-scopes-and-depth.md#self-development-scopes-self-) +in the user guide. **2. The membership tag — each stage's `scopes:` frontmatter.** A stage names the scopes it runs under in its own frontmatter, in `packages/framework/core/amadeus-common/stages//.md`: @@ -65,7 +68,7 @@ The exhaustive field-by-field contract — including how `keywords` are word-bou A scope and a stage point at each other from opposite ends, and it helps to hold both directions in view. -A **stage** declares its own identity — its phase, its lead agent, the artifacts it consumes and produces, and now the scopes it runs under (its `scopes:` list). A **scope** declares its identity in its own `.md` file — name, depth, keywords, description — with no per-stage membership inside it; membership lives on the stages. The binding between them is the scope name. When you add a new stage (see [Adding a Stage](02-adding-a-stage.md)), you put the scope membership *on that stage* — its `scopes:` list names every scope that should run it. A stage that names no scope is `SKIP` everywhere. The transpose at compile turns those per-stage lists into the grid, so membership is authored once, on the stage, rather than re-declared in ten separate scope blocks. +A **stage** declares its own identity — its phase, its lead agent, the artifacts it consumes and produces, and now the scopes it runs under (its `scopes:` list). A **scope** declares its identity in its own `.md` file — name, depth, keywords, description — with no per-stage membership inside it; membership lives on the stages. The binding between them is the scope name. When you add a new stage (see [Adding a Stage](02-adding-a-stage.md)), you put the scope membership *on that stage* — its `scopes:` list names every scope that should run it. A stage that names no scope is `SKIP` everywhere. The transpose at compile turns those per-stage lists into the grid, so membership is authored once, on the stage, rather than re-declared in a separate block per scope. That separation is the same data-versus-code line the rest of this guide rests on (see [Harness Engineer Guide](00-overview.md)). The scope file is data about *identity*; the stage's `scopes:` list is data about *membership*; the compiled grid is the transpose of the two. @@ -118,7 +121,7 @@ Tuning is a smaller edit, but it lands on the stage, not the scope. Two changes Either way, the recompile-and-doctor pair from step 3 above applies. The edit is small; the verification is the same. -A note on layering: tuning the shipped scopes edits framework-shipped files directly — a stage's `scopes:` tag or a shipped `packages/framework/core/scopes/amadeus-*.md`. That's legitimate for a fork that wants different defaults, but be aware you're changing files that carry the `amadeus-` lineage and a framework upgrade may want to reconcile them. Adding a net-new scope file alongside the shipped ten is the cleaner path when you want a team-specific behavior without touching the defaults everyone else relies on. +A note on layering: tuning the shipped scopes edits framework-shipped files directly — a stage's `scopes:` tag or a shipped `packages/framework/core/scopes/amadeus-*.md`. That's legitimate for a fork that wants different defaults, but be aware you're changing files that carry the `amadeus-` lineage and a framework upgrade may want to reconcile them. Adding a net-new scope file alongside the shipped ones is the cleaner path when you want a team-specific behavior without touching the defaults everyone else relies on. --- diff --git a/docs/harness-engineering/06-sensors.ja.md b/docs/harness-engineering/06-sensors.ja.md index a64db2d458..72e668a1f6 100644 --- a/docs/harness-engineering/06-sensors.ja.md +++ b/docs/harness-engineering/06-sensors.ja.md @@ -32,10 +32,11 @@ | `amadeus-answer-evidence.md` | ステージの `*-questions.md` | 記入済みの `[Answer]` が裁定参照(E-code)またはリーダー承認タイムスタンプを持つこと | | `amadeus-linter.md` | `.ts` / `.js` コード出力 | 設定されたリンター(デフォルトは ESLint)をラップする | | `amadeus-type-check.md` | `.ts` / `.tsx` コード出力 | 設定された型チェッカー(デフォルトは `tsc`)をラップする | +| `amadeus-event-registry-drift.md` | Event Registry と監査ツール | 監査イベント語彙、state-machine/hooks の参照集合、正典 Event Registry 集合の間の乖離および濃度ドリフト | | `amadeus-model-completeness.md` | TLA モデルとその正典実装ファイル | `FormalElection` TLA モデルと選挙実装との乖離 | | `amadeus-self-scope-consistency.md` | Amadeus の自己スコープファイルとコンパイル済みグリッド | 自己開発専用: 5つのドッグフード用ハーネス間で4つの `self-*` スコープが一致すること | -そのすべてが `matches:` グロブ(詳細は下記)でゲートされます。最初の2つのドキュメント形状チェックは成果物ツリーにスコープし(同梱マニフェストは `**/{amadeus-docs,intents}/**` を持ちます — intent ごとのレコードツリーで、移行前のプロジェクト向けにレガシーの `amadeus-docs/` アームを残しています)、2つのコード品質チェックはそれぞれの言語グロブ(`**/*.{ts,js}`、`**/*.{ts,tsx}`)に、answer-evidence チェックは questions ファイル(`**/*-questions.md`)に、モデルチェックは比較対象の spec と実装のパスにスコープします。自己スコープチェックは通常のプロジェクトでは休止し、`self-*` スコープが存在するときだけ有効になります。自分のものを記述する前に、`amadeus-required-sections.md` を最初から最後まで読んでください — 同梱の中で最も小さく、フロントマターと散文本文という全体の形を示しています。 +そのすべてが `matches:` グロブ(詳細は下記)でゲートされます。最初の2つのドキュメント形状チェックは成果物ツリーにスコープし(同梱マニフェストは `**/{amadeus-docs,intents}/**` を持ちます — intent ごとのレコードツリーで、移行前のプロジェクト向けにレガシーの `amadeus-docs/` アームを残しています)、2つのコード品質チェックはそれぞれの言語グロブ(`**/*.{ts,js}`、`**/*.{ts,tsx}`)に、answer-evidence チェックは questions ファイル(`**/*-questions.md`)に、event-registry ドリフトチェックは比較対象のレジストリと監査ツールに、モデルチェックは比較対象の spec と実装のパスにスコープします。自己スコープチェックは通常のプロジェクトでは休止し、`self-*` スコープが存在するときだけ有効になります。自分のものを記述する前に、`amadeus-required-sections.md` を最初から最後まで読んでください — 同梱の中で最も小さく、フロントマターと散文本文という全体の形を示しています。 --- diff --git a/docs/harness-engineering/06-sensors.md b/docs/harness-engineering/06-sensors.md index 1f9dacb325..41b2e49869 100644 --- a/docs/harness-engineering/06-sensors.md +++ b/docs/harness-engineering/06-sensors.md @@ -65,6 +65,7 @@ These manifests ship under `.claude/sensors/`, each prefixed `amadeus-`: | `amadeus-answer-evidence.md` | a stage's `*-questions.md` | A filled `[Answer]` carries a ruling reference (E-code) or a leader-approval timestamp | | `amadeus-linter.md` | `.ts` / `.js` code output | Wraps your configured linter (ESLint by default) | | `amadeus-type-check.md` | `.ts` / `.tsx` code output | Wraps your configured type-checker (`tsc` by default) | +| `amadeus-event-registry-drift.md` | the Event Registry and the audit tool | Divergence or cardinality drift across the audit event vocabulary, the state-machine/hooks reference set, and the canonical Event Registry set | | `amadeus-model-completeness.md` | the TLA model and its canonical implementation files | Drift between the `FormalElection` TLA model and the election implementation | | `amadeus-self-scope-consistency.md` | Amadeus self-scope files and compiled grids | Self-development only: parity of the four `self-*` scopes across the five dogfood harnesses | @@ -73,7 +74,8 @@ document-shape checks scope to the artifact tree (the shipped manifests carry `**/{amadeus-docs,intents}/**` — the per-intent record tree, with the legacy `amadeus-docs/` arm kept for a pre-migration project), the two code-quality checks to their language globs (`**/*.{ts,js}`, `**/*.{ts,tsx}`), the answer-evidence -check to the questions file (`**/*-questions.md`), and the model check to the +check to the questions file (`**/*-questions.md`), the event-registry drift check +to the registry and audit tool it compares, and the model check to the spec and implementation paths it compares. The self-scope check is dormant in ordinary projects and activates only when a `self-*` scope exists. Read `amadeus-required-sections.md` end to end before authoring your own — it is diff --git a/docs/harness-engineering/live-e2e.ja.md b/docs/harness-engineering/live-e2e.ja.md new file mode 100644 index 0000000000..727a229329 --- /dev/null +++ b/docs/harness-engineering/live-e2e.ja.md @@ -0,0 +1,91 @@ +# 実ハーネスのエンドツーエンド検証 + +> 言語: [English](live-e2e.md) | **日本語** + +このランブックは、Amadeus のハーネス配布物を実際の CLI とモデルに対して検証するための、opt-in かつローカル限定のジャーニーを説明します。型付きレジストリが静的な一次情報、JSONL 台帳が実行の事実の記録であり、以下のマトリクスは両者から生成されるビューです。 + +## 安全境界 + +ライブジャーニーは、opt-in 変数が設定されていても GitHub Actions 上では決して実行しません。各アダプタは専用の opt-in を持ち、受理する値は厳密な文字列 `1` だけです。子プロセスは新規に構築した許可リスト環境と短命のクレデンシャルリースを受け取ります。ソースの認証ファイル、ユーザー設定、ユーザーフック、ソースのホームパス、プロンプト、stdout/stderr の全文を、永続的な証跡として受け取ることも複製することもありません。 + +`codex-exec` アダプタは `AMADEUS_CODEX_EXEC_LIVE=1`、Codex CLI 0.139.0 以上、`dist/codex`、および `OPENAI_API_KEY` のクレデンシャルリースを要求します。`claude-print` アダプタは `AMADEUS_CLAUDE_PRINT_LIVE=1` を、`claude-tui` アダプタは `AMADEUS_TUI_LIVE=1` と tmux を要求します。`claude-print` と `claude-tui` はいずれも、計測済みのフラグを備えた Claude Code 2.1.220 以上と `dist/claude` を要求します。`claude-sdk` アダプタは別途 `AMADEUS_CLAUDE_SDK_LIVE=1`、Claude Agent SDK 0.3.158 以上、および `dist/claude` を要求します。Claude SDK と TUI の認証には短命の `ANTHROPIC_API_KEY` バインディングが必要です。Claude print は代わりに、検証済みのネイティブキーチェーンログインを使用できます。ソースの `HOME`、`CLAUDE_CONFIG_DIR`、ユーザー/ローカルの設定は、いずれの場合も転送しません。SDK アダプタは隔離されたワーカーグループ内で SDK クライアントとストリームを所有し、環境クレデンシャルを長さプレフィクス付きの stdin フレーム1本で転送し、クリーンアップの前に abort を TERM、KILL へとエスカレートします。 + +`kiro-tui` アダプタは `AMADEUS_KIRO_TUI_LIVE=1`、tmux、Kiro CLI 2.6.0 以上、および `dist/kiro` を要求します。Kiro は認証情報をユーザーのホーム配下のオンディスクデータベースに保持し、ホームごとのパスからチャットランタイムを再実行するため、環境クレデンシャルリースは存在しません。代わりにスクラッチホームがこの2つのソースエントリを参照でバインドします。クレデンシャルのバイト列がユーザーのホームを出ることはなく、スクラッチへ何も複製されず、アダプタがソースホーム配下へ書き込み・編集・削除を行うことはありません。スクラッチツリーを削除すればバインディング全体が消えます。ソースの `HOME`、`XDG_DATA_HOME`、`KIRO_HOME`、および周囲の AWS クレデンシャルを子プロセスへ転送することはありません。 + +クリーンアップは、もう1つの記録される結果ではなくバリアです。クリーンアップのエラー、リークの検出、リソースの残存は `cleanup-barrier-failed` を返し、実行とアサーションが成功していても台帳への追記を抑止します。`executed/asserted → cleanup-barrier-closed → ledger-appended|already-present → closure-committed` の順序だけが、PASS のレシートまたはサポートされたマトリクスへの投影を解放できます。 + +## ライブジャーニーの実行 + +Codex の直列ジャーニーは、クリーンなローカル worktree からのみ実行してください。 + +```bash +AMADEUS_CODEX_EXEC_LIVE=1 OPENAI_API_KEY='…' \ + bun test --timeout 180000 tests/e2e/t-exec-codex-kernel.serial.test.ts +``` + +ランナーは新しい Git プロジェクトと独立した Codex ホームを作成し、`dist/codex` だけをインストールし、`codex exec --json --ephemeral` プロセスを1つ起動し、exit・スキーマ・ファイルのアンカーを検査し、プロセスを回収し、クレデンシャルバインディングを破棄し、スクラッチリソースを削除します。opt-in、CLI、配布物、バージョン、クレデンシャルのいずれかが欠けている場合は、スクラッチを確保する前に機械可読なスキップを返します。 + +Claude print の直列ジャーニーは、クリーンなローカル worktree からのみ実行してください。 + +```bash +AMADEUS_CLAUDE_PRINT_LIVE=1 ANTHROPIC_API_KEY='…' \ + bun test --timeout 120000 tests/e2e/t-claude-print-kernel.serial.test.ts +``` + +Claude Code に使用可能なネイティブキーチェーンログインがある場合は `ANTHROPIC_API_KEY` を省略してください。ランナーはスクラッチを確保する前にネイティブクレデンシャルを検証します。`dist/claude` を新しい Git プロジェクトへコピーし、プロジェクトの `.claude/settings.json` へ厳密に `{ "hooks": {} }` を書き込み、新しい `HOME` と `TMPDIR` を設定し、`claude -p --setting-sources project --tools "" --no-session-persistence --output-format json --json-schema … --max-budget-usd 0.25` を起動します。成功には、クリーンアップと台帳への永続追記の前に、exit がゼロであること、`is_error=false`、ターンが1つ以上あること、そして閉じた構造化出力 `{ "amadeus_live_e2e": "ok" }` が必要です。 + +Claude Agent SDK の直列ジャーニーは、print のジャーニーとは独立に実行してください。 + +```bash +AMADEUS_CLAUDE_SDK_LIVE=1 ANTHROPIC_API_KEY='…' \ + bun test --timeout 120000 tests/e2e/t-claude-sdk-kernel.serial.test.ts +``` + +親プロセスは SDK クライアントを一切 import しません。新しいプロジェクト/ホームを作成し、SDK を所有するワーカーグループを1つ起動し、実行に束縛されたクレデンシャルフレームを1回だけ送信し、プロジェクト限定の設定でリテラルな `echo ok` プロンプトを駆動します。ワーカーは境界付きでサニタイズされた JSON イベントだけを発行します。成功には、終端の成功結果がちょうど1つ、正のターン数、パーミッション拒否がゼロ、順序付いた state/audit の観測、そして空でない tool-result または assistant バイトの証跡が必要です。90秒のデッドラインで SDK の abort を要求し、10秒待ってから TERM へ5秒、KILL/回収へ5秒とエスカレートします。単一イベントが 65,536 バイトを超える、イベント出力の合計が 1 MiB を超える、イベントが 4,096 個を超える、インメモリキューが 16 イベントまたは 256 KiB を超える、終端の重複や遅着、あるいはクリーンアップ/クレデンシャルのリークがあれば、いずれも非グリーンです。 + +Claude TUI の直列ジャーニーは、クリーンなローカル worktree からのみ実行してください。 + +```bash +AMADEUS_TUI_LIVE=1 ANTHROPIC_API_KEY='…' \ + bun test --timeout 180000 tests/e2e/t-claude-tui-kernel.serial.test.ts +``` + +TUI ランナーは、実行専用の `tmux -S` サーバーとセッションの内側で、プロジェクト限定の設定とスクラッチに閉じた `acceptEdits` パーミッションを与えて Claude を起動します。ペインが描画されるのを待ち、128 ビットの実行 ID に束縛されたプロンプトを1つ送信し、当該実行のファイルアンカーを厳密に検証し、境界付きのペインダイジェストだけを保持し、その後に台帳を呼び出せるようになる前へセッション・サーバー・クレデンシャル・スクラッチの各リソースを閉じます。デフォルトの tmux サーバー上のセッションを列挙・アタッチ・kill することは決してありません。 + +Kiro TUI の直列ジャーニーは、クリーンなローカル worktree からのみ実行してください。 + +```bash +AMADEUS_KIRO_TUI_LIVE=1 \ + bun test --timeout 240000 tests/e2e/t-kiro-tui-kernel.serial.test.ts +``` + +ランナーは `dist/kiro` を新しい Git プロジェクトへコピーし、新しい `HOME` と `TMPDIR` を設定し、ソースの認証データベースとチャットランタイムをスクラッチホームへバインドし、実行専用の `tmux -S` サーバーとセッションの内側で `kiro-cli chat --agent kiro_default --trust-all-tools` を起動します。組み込みエージェントを固定するのは意図的です。このジャーニーが計測するのは TUI のトランスポートであって同梱の conductor ではなく、conductor 自身のワークフロージャーニーは `tests/e2e/t-tui-kiro-*` にあります。実行専用のソケットは、スクラッチルート内に入れ子にするとプラットフォームの UNIX ドメインソケットのパス長制限を超えるため、システムの一時ディレクトリ配下に実行を識別する短い名前で作成し、クリーンアップで unlink します。trust-all の確認ピッカーを1回クリアし、入力フッターが描画されるのを待ち、128 ビットの実行 ID に束縛されたプロンプトを1つ送信し、当該実行のファイルアンカーを厳密に検証し、境界付きのペインダイジェストだけを保持し、その後に台帳を呼び出せるようになる前へセッション・サーバー・バインディング・スクラッチの各リソースを閉じます。デフォルトの tmux サーバー上のセッションを列挙・アタッチ・kill することは決してありません。認証は存在の有無だけを調べます。先に `kiro-cli login` を実行してください。また、このジャーニーは短いターン1回分の実際の Kiro クレジットを消費します。 + +## 台帳とマトリクス + +記録された実行は `tests/harness/live-e2e/runs.jsonl` へアトミックに追記されます。記録されるレシートにはアダプタ/バージョン/SHA/時刻/結果と境界付きのダイジェストが含まれ、生のクレデンシャル、ソースの絶対パス、プロンプト、出力の全文は決して含まれません。永続化の pending マーカーはグリーンの証跡ではありません。投影する前に、同一のレシートを回復してください。 + +派生マトリクスの描画・更新・検査は次で行います。 + +```bash +bun tests/harness/live-e2e/project-matrix.ts render +bun tests/harness/live-e2e/project-matrix.ts update +bun tests/harness/live-e2e/project-matrix.ts check +``` + +ライブテストが更新するのは台帳だけです。メンテナが明示的に `update` を実行し、生成されたブロックをレビューしてから `check` を実行します。ブロック内部の手編集はドリフトであり、コントラクトテストが失敗します。 + +生成されたマトリクスは英語版(`docs/harness-engineering/live-e2e.md`、冒頭の言語切替リンクから辿れます)が保持します。`project-matrix.ts` が書き込むのはそのファイルだけなので、最新の内容はそちらを参照してください。 + +## 配布物変更のトリガー + +`dist/`、ハーネスドライバ(Claude の print・SDK・TUI を含む)、またはインストーラを変更する intent を完了する前に、レジストリ上で影響を受けるアダプタをすべて特定し、それぞれのローカルライブジャーニーを1回実行してください。完了の証跡は、台帳上の pending を含まないレシートと、クリーンなマトリクス検査です。ユニットテストと fake を使った統合テストは、このライブの証跡を代替しません。 + +## トラブルシューティング + +- `CI_FORBIDDEN` または `OPT_IN_REQUIRED`: CI は無効のままにし、意図したローカル実行のときだけアダプタ固有の opt-in を設定してください。 +- `BINARY_MISSING`、`VERSION_UNSUPPORTED`、`DIST_MISSING`: サポート対象の CLI をインストールするか、フレームワークのソースから配布物を再生成してください。`dist/` を直接編集しないでください。 +- `AUTH_UNAVAILABLE`: 文書化された環境クレデンシャルリースを与えてください。ランナーをユーザーの認証/設定ディレクトリへ向けないでください。 +- `pending-durability`: 記録されたレシートを厳密に使って回復を再実行してください。マーカーやロックを手で削除しないでください。 +- `lock-timeout`: 所有者を調べてください。カーネルが自動的に回収するのは、死んでいると証明できる所有者か、スタンプのない stale なロックだけであり、生存中または不明な所有者を強制削除することはありません。 +- `generated-block-drift`: マトリクスの更新を明示的に実行し、差分をレビューしてから検査を再実行してください。 diff --git a/docs/harness-engineering/live-e2e.md b/docs/harness-engineering/live-e2e.md index 655585f599..50fa0a25f4 100644 --- a/docs/harness-engineering/live-e2e.md +++ b/docs/harness-engineering/live-e2e.md @@ -1,5 +1,7 @@ # Live Harness End-to-End Verification +> Languages: **English** | [日本語](live-e2e.ja.md) + This runbook describes the opt-in, local-only journey used to verify an Amadeus harness distribution against a real CLI and model. The typed registry is the static source of truth, the JSONL ledger records run facts, and the matrix below is a generated view of both. ## Safety boundary diff --git a/docs/reference/01-architecture.ja.md b/docs/reference/01-architecture.ja.md index 83b336cea3..446108f7dc 100644 --- a/docs/reference/01-architecture.ja.md +++ b/docs/reference/01-architecture.ja.md @@ -424,7 +424,7 @@ amadeus/ # neutral, harness-independent, comm 7. **フラットなエージェントファイル** — 各エージェントは `agents/` 内の単一の `.md` ファイルです(`agent.md` + `knowledge/` を持つサブディレクトリではありません)。これは構造を簡素化し、エージェントを発見しやすくします。方法論の知識は別途 `knowledge/[agent]/` に存在します。 -8. **スコープ駆動の適応的深度** — 10個の名前付きスコープ(enterprise、feature、mvp、poc、fix、chore、refactor、infra、security-patch、workshop)に加え自動検出が、どのステージがどの深度で実行されるかを決定します。各スコープは `.claude/scopes/amadeus-.md` ファイル(アイデンティティ)です。メンバーシップはステージごとの `scopes:` フロントマタータグで、コンパイル時に EXECUTE/SKIP グリッド(`.claude/tools/data/scope-grid.json`、権威)に転置され、SKILL.md 内のサマリーテーブル(情報提供用)へコンパイルされます。自然言語のキーワード→スコープ推論は、各スコープの `.md` フロントマターから `keywords` を読みます。ユーザーは任意の承認ゲートでオーバーライドできます。 +8. **スコープ駆動の適応的深度** — 15個の名前付きスコープ(enterprise、feature、mvp、poc、fix、chore、refactor、infra、installer-distribution、security-patch、self-document、self-feature、self-fix、self-refactor、workshop)に加え自動検出が、どのステージがどの深度で実行されるかを決定します。各スコープは `.claude/scopes/amadeus-.md` ファイル(アイデンティティ)です。メンバーシップはステージごとの `scopes:` フロントマタータグで、コンパイル時に EXECUTE/SKIP グリッド(`.claude/tools/data/scope-grid.json`、権威)に転置され、SKILL.md 内のサマリーテーブル(情報提供用)へコンパイルされます。自然言語のキーワード→スコープ推論は、各スコープの `.md` フロントマターから `keywords` を読みます。ユーザーは任意の承認ゲートでオーバーライドできます。 9. **最小限のルール** — ガードレール(合計約35行)のみが space メモリ層(`amadeus/spaces//memory/`、`.claude/rules/amadeus.md` の @-import スタブ経由でプルされる)に存在します。それ以外すべて(検証、ブラウンフィールドのセーフガード、監査フォーマット、適応パターン)は `knowledge/amadeus-shared/` に存在するか、SKILL.md/stage-protocol.md に埋め込まれています。ルールは常にロードされるため、これにより非 AI-DLC の会話でのコンテキスト肥大化を防ぎます。 diff --git a/docs/reference/01-architecture.md b/docs/reference/01-architecture.md index d91d4d2142..8f0d04a4c8 100644 --- a/docs/reference/01-architecture.md +++ b/docs/reference/01-architecture.md @@ -463,7 +463,7 @@ appends — there is intentionally no `merge=union` attribute. 7. **Flat agent files** -- Each agent is a single `.md` file in `agents/` (not a subdirectory with `agent.md` + `knowledge/`). This simplifies the structure and makes agents discoverable. Methodology knowledge lives separately in `knowledge/[agent]/`. -8. **Scope-driven adaptive depth** -- Ten named scopes (enterprise, feature, mvp, poc, fix, chore, refactor, infra, security-patch, workshop) plus auto-detect determine which stages execute and at what depth. Each scope is a `.claude/scopes/amadeus-.md` file (identity); membership is a per-stage `scopes:` frontmatter tag, transposed at compile into the EXECUTE/SKIP grid (`.claude/tools/data/scope-grid.json`, authoritative) and compiled into a summary table in SKILL.md (informational). NL keyword→scope inference reads each scope's `keywords` from its `.md` frontmatter. The user can override at any approval gate. +8. **Scope-driven adaptive depth** -- Fifteen named scopes (enterprise, feature, mvp, poc, fix, chore, refactor, infra, installer-distribution, security-patch, self-document, self-feature, self-fix, self-refactor, workshop) plus auto-detect determine which stages execute and at what depth. Each scope is a `.claude/scopes/amadeus-.md` file (identity); membership is a per-stage `scopes:` frontmatter tag, transposed at compile into the EXECUTE/SKIP grid (`.claude/tools/data/scope-grid.json`, authoritative) and compiled into a summary table in SKILL.md (informational). NL keyword→scope inference reads each scope's `keywords` from its `.md` frontmatter. The user can override at any approval gate. 9. **Minimal rules** -- Only guardrails (~35 lines total) live in the space memory layer (`amadeus/spaces//memory/`, pulled in via the `.claude/rules/amadeus.md` @-import stub). Everything else (verification, brownfield safeguards, audit format, adaptive patterns) lives in `knowledge/amadeus-shared/` or is embedded in SKILL.md/stage-protocol.md. This prevents context bloat in non-AI-DLC conversations since rules are always loaded. diff --git a/docs/reference/07-sensor-system.ja.md b/docs/reference/07-sensor-system.ja.md index 7cfe5ba2b9..d43c114f2a 100644 --- a/docs/reference/07-sensor-system.ja.md +++ b/docs/reference/07-sensor-system.ja.md @@ -21,7 +21,7 @@ > `amadeus/spaces//intents/-