diff --git a/docs/README.ja.md b/docs/README.ja.md index 5c93e5d675..733e878790 100644 --- a/docs/README.ja.md +++ b/docs/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の違い @@ -37,6 +38,7 @@ Harness Engineer Guide と Developer Reference の境界は **データ対コー - [新規プロトコルへ形式モデルを供給する](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 f2d85ea417..4fde29b88c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -40,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 @@ -52,6 +53,7 @@ to add one. - [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/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/research/upstream-sync/reports/v2.2.0-to-v2.3.0-plan.md b/docs/research/upstream-sync/reports/v2.2.0-to-v2.3.0-plan.md index 0619abbe93..9a88bac082 100644 --- a/docs/research/upstream-sync/reports/v2.2.0-to-v2.3.0-plan.md +++ b/docs/research/upstream-sync/reports/v2.2.0-to-v2.3.0-plan.md @@ -1,5 +1,10 @@ # Upstream AI-DLC sync plan: v2.2.0 to v2.3.0 +> **Frozen record.** This report is a frozen snapshot of the investigation as it +> stood when it was written; the exact revisions it was taken against are pinned +> in [Compared revisions](#compared-revisions) below. It is not maintained after +> that point and does not reflect the current state of Amadeus or of upstream. + ## Executive summary This plan compares upstream `awslabs/aidlc-workflows` v2.2.0 to v2.3.0 and maps