sync: update from private repo (e62f5c7)

docs/architecture.md

@@ -1,85 +1,86 @@
+English | [日本語](architecture.ja.md)
+
 # Architecture Overview
 
-MAESTRO は、ユーザーが投げたタスクを LLM 駆動のワークフロー（Piece）で実行する
-エージェントオーケストレーターである。コントリビュータ向けのコードマップは
-[../AGENTS.md](../AGENTS.md) も参照。
+MAESTRO is an agent orchestrator that runs the tasks a user submits with LLM-driven workflows (Pieces).
+For a code map aimed at contributors, see also [../AGENTS.md](../AGENTS.md).
 
-## 実行フロー
+## Execution flow
 
 ```
 UI (POST /api/local/tasks)
   → bridge/server.ts (Express API)
-  → Repository (SQLite: jobs テーブルに enqueue)
-  → Worker.poll() が queued ジョブを取得
-  → piece-classifier.ts: LLM がタスクを分類し Piece を選択
-  → piece-runner.ts: pieces/*.yaml を読み、movements を順に実行
-  → agent-loop.ts: 1 movement の ReAct ループ (LLM ↔ tool calls)
-      ├─ 中間遷移: transition ツール
-      └─ 終了:     complete ツール (success / aborted / needs_user_input)
-  → ジョブ完了: DB 更新 + 進捗コメント。成果物は workspace/output/
+  → Repository (SQLite: enqueue into the jobs table)
+  → Worker.poll() picks up queued jobs
+  → piece-classifier.ts: the LLM classifies the task and selects a Piece
+  → piece-runner.ts: reads pieces/*.yaml and runs the movements in order
+  → agent-loop.ts: the ReAct loop for one movement (LLM ↔ tool calls)
+      ├─ intermediate transition: the transition tool
+      └─ termination:             the complete tool (success / aborted / needs_user_input)
+  → job complete: update DB + post a progress comment. Deliverables go to workspace/output/
 ```
 
-1. **API 受付** — `bridge/server.ts` がタスクを受け、`Repository` 経由で `jobs` テーブルに `queued` で登録する。
-2. **ワーカー** — `worker.ts` が DB をポーリングし、自分の `profiles`/`task_classes` に合致するジョブを取得（複数ワーカーが並走）。
-3. **分類** — `piece-classifier.ts` がタスク本文と全 Piece の description を LLM に渡し、最適な Piece を選ぶ。
-4. **Piece 実行** — `piece-runner.ts` が Piece の movements を順に回す。verify movement のフィードバックは次の execute に引き継がれ、`transition.lessons` で movement 間の教訓が蓄積される。
-5. **ReAct ループ** — `agent-loop.ts` が 1 movement 内で LLM とツールを往復させる。`ContextManager` が LLM の `usage` からトークン使用量を追跡し、閾値（70/85/95%）で warn / prompt / force_transition を発火する。
+1. **API intake** — `bridge/server.ts` receives the task and registers it in the `jobs` table as `queued` via the `Repository`.
+2. **Worker** — `worker.ts` polls the DB and picks up jobs matching its `profiles`/`task_classes` (multiple workers run in parallel).
+3. **Classification** — `piece-classifier.ts` passes the task body and the descriptions of all Pieces to the LLM and chooses the best-fit Piece.
+4. **Piece execution** — `piece-runner.ts` iterates through the Piece's movements in order. Feedback from a verify movement is carried over to the next execute, and lessons between movements accumulate via `transition.lessons`.
+5. **ReAct loop** — `agent-loop.ts` shuttles between the LLM and tools within one movement. `ContextManager` tracks token usage from the LLM's `usage` and fires warn / prompt / force_transition at thresholds (70/85/95%).
 
-## Piece と Movement
+## Piece and Movement
 
-- **Piece** = `pieces/*.yaml`。`movements` 配列で構成。
-- 各 **Movement** は `allowed_tools`（LLM に提示するツール）、`edit`（Write/Edit 可否）、`rules`（遷移条件）を持つ。`allowed_tools` 外のツールは LLM から見えない。
-- **遷移**: 中間ホップは `transition`（`rules[].next` に列挙した宛先のみ選択可）、終了は `complete`。`complete.result` がユーザーに見える唯一の最終出力。
-- **`default_next`** はエンジン内部の sentinel（コンテキスト溢れ時の強制遷移、ASK 上限時のフォールバック）。
-- **Progressive pressure**: 同一 movement への連続訪問が増えると警告を注入し、閾値超過で ABORT。
+- **Piece** = `pieces/*.yaml`. Composed of a `movements` array.
+- Each **Movement** has `allowed_tools` (the tools presented to the LLM), `edit` (whether Write/Edit is allowed), and `rules` (transition conditions). Tools outside `allowed_tools` are invisible to the LLM.
+- **Transitions**: an intermediate hop uses `transition` (only the destinations listed in `rules[].next` are selectable); termination uses `complete`. `complete.result` is the only final output visible to the user.
+- **`default_next`** is an engine-internal sentinel (forced transition on context overflow, fallback at the ASK limit).
+- **Progressive pressure**: as consecutive revisits to the same movement increase, warnings are injected, and exceeding the threshold triggers ABORT.
 
-## ツールランタイム
+## Tool runtime
 
-ツールは `src/engine/tools/*.ts` のモジュール群。`tools/index.ts` が動的にロードし dispatch する。各ツールは 1 行の description（毎 LLM 呼び出しに乗るため簡潔に）を持ち、詳細手順は `docs/tools/<name>.md`（`ReadToolDoc` で取得）に置く。主なモジュールは [../AGENTS.md](../AGENTS.md#tool-modules) の一覧を参照。
+Tools are a set of modules in `src/engine/tools/*.ts`. `tools/index.ts` loads and dispatches them dynamically. Each tool has a one-line description (kept concise because it rides on every LLM call), and detailed instructions live in `docs/tools/<name>.md` (fetched with `ReadToolDoc`). For the main modules, see the list in [../AGENTS.md](../AGENTS.md#tool-modules).
 
-Read 系ツールは並列実行される。Write/Edit は movement の `edit: true` のときのみ提示され、書き込みは主に `workspace/output/` に限られる。
+Read-type tools run in parallel. Write/Edit is only presented when the movement has `edit: true`, and writes are mostly limited to `workspace/output/`.
 
-## Bash サンドボックス
+## Bash sandbox
 
-エージェントの Bash 実行は、利用可能なら **bwrap サンドボックス**で隔離する:
+The agent's Bash execution is isolated with the **bwrap sandbox** when available:
 
-- **ファイルシステム**: タスクの workspace のみ rw bind、`/usr` 等は ro、他タスクの workspace やホスト `/home` は不可視。
-- **環境変数**: `--clearenv` + 最小 allowlist のみ注入（シークレット env はサンドボックス内から見えない）。
-- **ネットワーク**: `--unshare-net` で遮断（外向き通信は SSRF ガード付きの WebFetch/MCP に集約）。
-- **各 Bash コールは独立**したサンドボックス（揮発 `/tmp`・毎回新名前空間）。永続するのは workspace のみ。
+- **Filesystem**: only the task's workspace is rw-bound, `/usr` etc. are ro, and other tasks' workspaces and the host `/home` are invisible.
+- **Environment variables**: `--clearenv` + injecting only a minimal allowlist (secret env vars are invisible from inside the sandbox).
+- **Network**: blocked with `--unshare-net` (outbound communication is consolidated into WebFetch/MCP with SSRF guards).
+- **Each Bash call** gets an independent sandbox (volatile `/tmp`, a fresh namespace each time). Only the workspace persists.
 
-`safety.bash_sandbox` でモードを選ぶ（`auto`/`always`/`off`）。bwrap 不在時は **hardened フォールバック**（コマンド許可リスト + パススコープ検査 + env スクラブ付き exec）になる。実行時 `pip`/`npm install` は全モードで拒否され、Python パッケージは `runtime/python-requirements.txt` からプリベイクされる。詳細は [operations/bash-sandbox-provisioning.md](operations/bash-sandbox-provisioning.md)。
+`safety.bash_sandbox` selects the mode (`auto`/`always`/`off`). When bwrap is absent, it falls back to a **hardened fallback** (an exec with a command allowlist + path-scope checks + env scrubbing). Runtime `pip`/`npm install` are rejected in all modes, and Python packages are pre-baked from `runtime/python-requirements.txt`. For details, see [operations/bash-sandbox-provisioning.md](operations/bash-sandbox-provisioning.md).
 
-## ワークスペース構造（ジョブ実行時）
+## Workspace structure (during job execution)
 
 ```
 {worktree_dir}/local/{taskId}/
-  input/    アップロード・DownloadFile の保存先
-  output/   成果物（Write/Edit が許可される主な場所）
-  logs/     activity.log / 各種履歴
-  subtasks/ SpawnSubTask の結果
-  skills/   ReadSkill で materialize されたスキルファイル
+  input/    where uploads and DownloadFile saves go
+  output/   deliverables (the main place where Write/Edit is allowed)
+  logs/     activity.log / various histories
+  subtasks/ results from SpawnSubTask
+  skills/   skill files materialized by ReadSkill
 ```
 
-## データベース
+## Database
 
-SQLite（better-sqlite3）。`db/schema.sql` が初期スキーマ。追加カラムは `db/migrate.ts` で
-`PRAGMA table_info` → 存在チェック → `ALTER TABLE ADD COLUMN` のパターンで冪等に適用する
-（バージョン管理テーブルは使わない）。主なテーブル: `jobs` / `local_tasks` /
-`local_task_comments` / `audit_log` ほか。
+SQLite (better-sqlite3). `db/schema.sql` is the initial schema. Additional columns are applied idempotently in `db/migrate.ts`
+with the pattern `PRAGMA table_info` → existence check → `ALTER TABLE ADD COLUMN`
+(no version-management table is used). Main tables: `jobs` / `local_tasks` /
+`local_task_comments` / `audit_log`, and others.
 
-## ジョブのライフサイクル
+## Job lifecycle
 
-`queued` → `dispatching` → `running` → `succeeded` / `failed` / `waiting_human`（ASK 回答待ち）/ `waiting_subtasks`（並列サブタスク待ち）。失敗時は `retry` で再 `queued`（最大 `retry.max_attempts` 回）。
+`queued` → `dispatching` → `running` → `succeeded` / `failed` / `waiting_human` (waiting for an ASK answer) / `waiting_subtasks` (waiting for parallel subtasks). On failure, `retry` re-queues it (up to `retry.max_attempts` times).
 
-## オプションのサブシステム
+## Optional subsystems
 
-- **LLM Gateway**（`src/gateway/`） — MAESTRO 自身を OpenAI 互換 LLM プロキシとして公開（仮想キー・予算・Prometheus メトリクス）。複数 GPU/チーム共有向け。env/接続種別が `AAO_*`/`aao_gateway` の歴史的接頭辞を使う。
-- **MCP** — Model Context Protocol サーバー連携（`MCP_ENCRYPTION_KEY` 必須）。
-- **Reflection** — ジョブ完了ごとにユーザーメモリを LLM が自動更新（既定 OFF、revert 可）。
-- **認証** — Passport による Google/Gitea OAuth（任意）。`private`/`org`/`public` の可視性モデル。
-- **スケジューラ** — cron 式の定期タスク。
+- **LLM Gateway** (`src/gateway/`) — exposes MAESTRO itself as an OpenAI-compatible LLM proxy (virtual keys, budgets, Prometheus metrics). For sharing across multiple GPUs/teams. Its env vars and connection type use the historical `AAO_*`/`aao_gateway` prefixes.
+- **MCP** — Model Context Protocol server integration (`MCP_ENCRYPTION_KEY` required).
+- **Reflection** — the LLM automatically updates user memory after each job completes (OFF by default, revertible).
+- **Authentication** — Google/Gitea OAuth via Passport (optional). A `private`/`org`/`public` visibility model.
+- **Scheduler** — cron-expression scheduled tasks.
 
-## フロントエンド
+## Frontend
 
-React + Vite + TailwindCSS + @tanstack/react-query。`ui/src/App.tsx` がルート。2 カラム（list + detail）レイアウトで、タスク一覧・スケジュール・設定・スキル/Piece 管理を扱う。
+React + Vite + TailwindCSS + @tanstack/react-query. `ui/src/App.tsx` is the root. A two-column (list + detail) layout handles the task list, schedule, settings, and skill/Piece management.