aizuchi 0.4.0 → 0.7.2

package/README.md

@@ -1,211 +1,273 @@
+English | [日本語](README.ja.md)
+
 # AIzuchi
 
-**AI進捗管理カンバンダッシュボード**（npm / CLI 名: `aizuchi`）
+**A local kanban dashboard for the work you delegate to AI coding agents** (npm / CLI name: `aizuchi`)
 
-CLI 型 AI コーディングエージェント（Claude Code 等）に作業を委任するプロジェクトで、人間が
-ブラウザ上のカンバンボードからタスクの進捗を一望・操作するためのローカル専用ツールです。
-タスクは `.kanban/` 配下のプレーンテキスト（Markdown + YAML frontmatter）が唯一の正で、
-AI も人間も通常のファイル読み書きだけで参加できます。
+You hand work to a CLI-based AI coding agent (Claude Code and the like), then watch and steer its
+progress on a kanban board in your browser. Tasks are plain text under `.kanban/`
+(Markdown + YAML frontmatter) — that file is the single source of truth, and both the AI and you
+take part by simply reading and writing files.
 
-「相槌（あいづち）」＝対話せずに通じ合う、AI との意思疎通を表す命名です。
+The name comes from *aizuchi* (相槌) — the small back-channel cues that let two people stay in sync
+without spelling everything out: the quiet understanding between you and your AI.
 
-- **ローカル限定**: `127.0.0.1` のみにバインドし、外部送信・テレメトリは一切しません。
-- **ファイルが唯一の正**: DB を使いません。git 管理でき、サーバー停止中も読めます。
-- **規約ベースの AI 連携**: AI は専用 API なしで、ファイル読み書きだけで参加します。
+- **Local only** — binds to `127.0.0.1` only. No outbound requests, no telemetry, ever.
+- **Files are the source of truth** — no database. Everything is git-trackable and still readable
+  while the server is stopped.
+- **Convention-based AI integration** — the AI needs no special API or SDK; it joins by reading and
+  writing the same files you do.
 
-変更履歴は [CHANGELOG.md](CHANGELOG.md) を参照してください。
+See [CHANGELOG.md](CHANGELOG.md) for the version history.
 
-## 必要環境
+## Requirements
 
-- Node.js **20.1 以上**（`fs.readdir` の `recursive` を使うため）
-- macOS / Linux / WSL（Windows ネイティブはベストエフォート）
+- Node.js **20.1 or newer** (uses the `recursive` option of `fs.readdir`)
+- macOS / Linux / WSL (native Windows is best-effort)
 
-## クイックスタート
+## Quick start
 
 ```bash
-# 対象プロジェクトのディレクトリ直下で実行する
-npx aizuchi init     # .kanban/ を生成 + CLAUDE.md へ運用規約をマーカー区切りで追記
-npx aizuchi          # = serve。http://127.0.0.1:5151 でボードを起動（Ctrl+C で終了）
+# Run from the root of the project you want to manage
+npx aizuchi init     # creates .kanban/ and appends the operating rules to CLAUDE.md (marker-delimited)
+npx aizuchi          # = serve. Opens the board at http://127.0.0.1:5151 (Ctrl+C to stop)
 
-# 複数プロジェクトをまとめて見る（read-only 集約・既定ポート 5152）
-npx aizuchi overview <dir...>   # 例: npx aizuchi overview ~/proj-a ~/proj-b
+# View several projects at once (read-only aggregation, default port 5152)
+npx aizuchi overview <dir...>   # e.g. npx aizuchi overview ~/proj-a ~/proj-b
 ```
 
-- `init` は既存ファイルを壊しません。既に `.kanban/` があれば安全に中断します。
-  CLAUDE.md は末尾にマーカー（`<!-- aizuchi:begin -->`〜`<!-- aizuchi:end -->`）区切りで追記し、
-  再実行時は同区間だけを置き換えます（冪等）。撤去は `.kanban/` 削除とマーカー区間削除だけで完了します。
-- `--port <番号>` でポート変更、`--member <ID>` で AI のメンバー ID 指定（config.members に未登録なら
-  `ai` 種別で追加）、`--yes` で確認プロンプト省略。
-- `overview` は各 dir の `.kanban` を読み取り専用で集約表示します（編集・起票・D&D なし）。
-  `.kanban` の無い dir や同一 dir の重複指定は明確なエラーで起動を拒否します。既定ポートは
-  serve（5151）と衝突しない 5152 で、`--port <番号>` で変更できます。
-- `127.0.0.1` 以外にはバインドせず、外部へのネットワーク送信は一切行いません。
-
-## できること
-
-ブラウザのボードで AI への委任を一望・操作します。エディタや AI がファイルを書き換えると、
-watcher → SSE で開いているボードへ約 1 秒以内に反映されます（ライブ更新）。
-UI 表示言語は英語 / 日本語（en / ja・既定 en）を切り替えられます。
-
-### ボード運用
-
-- **ドラッグ＆ドロップ**: カラム移動で frontmatter の `status` / `updated` だけをピンポイント書換（本文は保全）。
-  Pending へ移すと種別（decision / external / dependency）と理由を尋ねるダイアログが出ます。
-- **検索フィルタ**: タイトル / ラベル / 担当でカードを絞り込み。
-- **Saved Views（保存済みビュー）**: 絞り込み条件を config に名前付きで保存し、chip からワンクリックで適用。
-- **新着ハイライト**: 画面を見ていない間に AI が動かしたタスク（status 変化 / 作業ログ追記 / 新規）を
-  カードのハイライトと「新着」バッジで可視化。カードを開くと既読化、ヘッダから一括既読も可能。
-- **停滞バッジ**: 一定期間更新が止まったタスクにバッジを表示（閾値は status 別に設定可能）。
-- **差し戻し（やり直しを依頼）**: カード / 詳細から理由を添えて `todo` へ戻し、作業ログに記録。
-  直近の差し戻し理由は再依頼の指示コピーに自動で載ります。
-- **複数選択の一括指示コピー**: 複数選択モードでカードを選び、依存関係のトポロジカル順に並べた
-  1 つの指示文へまとめてクリップボードへコピー（AI へのバッチ委任を 1 操作で）。
-- **ドラッグ横パン**: カラムの空白部分を掴んで横スクロール（カード等のインタラクティブ要素からの操作は除外）。
-
-### 見通し
-
-- **クリティカルパス**: `depends_on` の DAG をトポロジカル深さで列配置し、クリティカルパスを強調。
-  循環は検出して警告し、再編成の指示コピーも提供。
-- **マイルストーン**: 予定表（milestone 別・done/total 付き）と対応履歴（月別）の 2 ペイン表示。
-- **日次ダイジェスト**: 日付別に作業ログをまとめて表示。
-- **統計**: 完了数推移 / サイクルタイム / ステータス滞留 / member 別完了数 / ボトルネック /
-  停滞中（静かな）タスクの一覧。
-
-### 管理と健全性
-
-- **アーカイブ検索 + 復元**: done タスクを archive へ退避し、一覧・検索・プレビュー。
-  「ボードに戻す」で `tasks/` へ復元（unarchive）。
-- **ごみ箱（.trash 退避 + 復元）**: タスクを破壊的に書き換える直前に旧版を `.kanban/.trash/` へ
-  自動退避する安全網。一覧・現行との差分プレビュー・復元が可能（誤上書きからの回復）。
-- **AI 設定ファイル管理**: `aiConfigPaths` で許可したファイル（CLAUDE.md / settings 等）を
-  GUI から編集（JSON 構文チェック・`.bak` バックアップ・パーミッション保全）。
-- **git 履歴連携（read-only）**: 詳細パネルのコミットタブで、タスク ID を含むコミット履歴を表示。
-  `git log` を read-only で実行するだけで、fetch / pull 等の外部通信はしません。
-
-### AI 連携規約 + CLI
-
-- **規約ベースの連携**: `init` が CLAUDE.md に運用規約（着手 / 進捗 / 完了 / ブロック / 起票 / 書式）を
-  マーカー区切りで追記。AI は専用 API なしでファイルを読み書きするだけで参加できます。
-- **提案ワークフロー**: `aiTaskCreation` が `proposal` のとき、AI 起票は `proposed` で入り、
-  承認 / 却下を経て `todo` へ。モード違反は警告で検知。
-- **AI 用 CLI（必須でない安全弁）**: 書込系 `aizuchi task add / move <id> <status> / done <id> /
-  block <id> --type --reason / log <id> "msg" / comment <id> "msg" / revise <id> --reason` と、
-  読取系 `list [--status S] [--assignee M] / show <id> / next`（着手可能なタスクを依存解決順に提示）を提供。
-  いずれも既存のスキーマ検証・採番直列化・行置換検証を再利用します（生ファイル編集も従来どおり可・`--json` 対応）。
-
-### そのほか
-
-- **複数案件横断 overview**: `aizuchi overview <dir...>` で複数 `.kanban` を read-only 集約表示。
-- **コマンドパレット ⌘K**: ビュー切替 / タスク検索ジャンプ / 起票 / 設定を 1 操作で。
-- **タスク詳細**: Markdown プレビュー / 本文編集（保存時に競合検知 → 行差分提示）/
-  作業ログ・やりとり（双方向コメント）のタイムライン。
-- **警告バナー**: 壊れた frontmatter・重複 ID・未登録メンバー・不正な config を表示（ボードは落ちません）。
-
-## 開発
+- `init` never clobbers existing files. If `.kanban/` already exists, it stops safely.
+  It appends to CLAUDE.md inside markers (`<!-- aizuchi:begin -->` … `<!-- aizuchi:end -->`) and on
+  re-run replaces only that section (idempotent). To remove it, delete `.kanban/` and the marked
+  section — that's all.
+- `--port <n>` changes the port, `--member <id>` sets the AI's member ID (added with the `ai` kind
+  if it isn't already in `config.members`), and `--yes` skips the confirmation prompt.
+- `overview` aggregates each directory's `.kanban` read-only (no editing, no creating tasks, no
+  drag & drop). Directories without a `.kanban`, or the same directory passed twice, are rejected
+  with a clear error at startup. The default port is 5152 so it doesn't collide with `serve`
+  (5151); change it with `--port <n>`.
+- It binds to `127.0.0.1` only and makes no outbound network requests whatsoever.
+
+## What it does
+
+The board lets you see and steer everything you've delegated to the AI. When your editor or the AI
+rewrites a file, the change reaches any open board within about a second (live updates via
+watcher → SSE). The UI language can be switched between English and Japanese (`en` / `ja`, default
+`en`).
+
+### Board operations
+
+- **Drag & drop** — moving a card between columns pinpoint-writes only the `status` / `updated`
+  frontmatter fields (the body is preserved). Moving to Pending opens a dialog asking for the
+  block kind (decision / external / dependency) and a reason.
+- **Search filter** — narrow cards by title, label, or assignee.
+- **Saved views** — store filter conditions by name in the config and apply them in one click from
+  a chip.
+- **"Assigned to me" filter** — pick yourself (a member) in the header to narrow the board, in one
+  tap, to just the tasks coming your way: ones assigned to you, ones that `@mention` you in the body,
+  and ones you created that are awaiting approval (`proposed`). Handy for checking your own queue
+  first thing in the morning when several people / AIs are working at once. The choice is stored in
+  this browser only and never touches the task files.
+- **Pin / focus** — pin a task you want to keep an eye on from its card or detail with 📌, and it
+  stays at the top of Home. Pins to tasks that become done or archived hide themselves automatically.
+  Separate from the auto-computed critical path, you can always see the tasks you chose to watch. The
+  pin set is kept in this browser only.
+- **New-activity highlight** — tasks the AI moved while you weren't looking (status change, new work
+  log entry, brand-new task) are surfaced with a card highlight and a "new" badge. Opening a card
+  marks it read; the header offers mark-all-read.
+- **Stale badge** — a badge appears on tasks that haven't been updated for a while (the threshold is
+  configurable per status).
+- **Send back (ask for a redo)** — from a card or its detail, return a task to `todo` with a reason
+  that's recorded in the work log. The most recent send-back reason is auto-included in the
+  re-delegation instruction copy.
+- **Quick comment from a card** — add a one-line comment straight to the exchanges (two-way
+  comments) section from a card, without opening the detail panel, so the back-and-forth with the AI
+  gets one step faster.
+- **Batch instruction copy for multiple selections** — in multi-select mode, pick several cards and
+  copy a single instruction that orders them topologically by dependency, so you can batch-delegate
+  to the AI in one action.
+- **Drag-to-pan** — grab the empty area of a column to scroll horizontally (interactions starting
+  from cards and other interactive elements are excluded).
+
+### Visibility
+
+- **Critical path** — lays out the `depends_on` DAG in columns by topological depth and highlights
+  the critical path. Cycles are detected and warned about, with a reorganization instruction copy
+  provided.
+- **Milestones** — a two-pane view of the schedule (per milestone, with done/total) and the history
+  of completed work (by month).
+- **Daily digest** — work-log entries grouped and shown by date.
+- **Stats** — completion-count trend, cycle time, time-in-status, completions by member,
+  bottlenecks, and a list of stalled (quiet) tasks.
+- **AI activity heatmap** — the stats view also aggregates work-log timestamps into a weekday × hour
+  heatmap, so you can see at a glance when the AI tends to be working (display only).
+
+### Management and health
+
+- **Archive search + restore** — move done tasks into the archive to list, search, and preview.
+  "Return to board" restores them to `tasks/` (unarchive).
+- **Trash (.trash backup + restore)** — a safety net that automatically backs up the old version to
+  `.kanban/.trash/` just before a task is destructively rewritten. You can list, preview the diff
+  against the current version, and restore (recovery from accidental overwrites).
+- **Permanent task deletion** — the task detail offers "Delete permanently" (archive stays the
+  primary choice; delete is separated out as a dangerous operation, with a confirmation). A task
+  being deleted is always backed up to the trash (`.kanban/.trash`) before it is removed, so it can
+  be restored later. If the backup fails, the deletion is aborted (to prevent irreversible loss).
+- **AI config file management** — edit files allowed via `aiConfigPaths` (CLAUDE.md, settings, etc.)
+  from the GUI, with JSON syntax checking, a `.bak` backup, and permission preservation.
+- **Git history integration (read-only)** — the commits tab in the detail panel shows commit history
+  that mentions the task ID. It only runs `git log` read-only — no fetch, pull, or other outbound
+  communication.
+
+### AI integration rules + CLI
+
+- **Convention-based integration** — `init` appends the operating rules (start / progress / done /
+  block / create / format) to CLAUDE.md inside markers. The AI takes part by reading and writing
+  files, with no special API needed.
+- **Proposal workflow** — when `aiTaskCreation` is `proposal`, AI-created tasks enter as `proposed`
+  and reach `todo` only after approval / rejection. Mode violations are surfaced as warnings.
+- **AI-facing CLI (an optional safety valve)** — write commands `aizuchi task add / move <id> <status> /
+  done <id> / block <id> --type --reason / log <id> "msg" / comment <id> "msg" / revise <id> --reason`,
+  plus read commands `list [--status S] [--assignee M] / show <id> / next` (proposes the next
+  actionable tasks in dependency-resolved order). All of these reuse the existing schema validation,
+  serialized ID numbering, and line-replacement checks (editing raw files directly still works too;
+  `--json` is supported).
+
+### Also
+
+- **Cross-project overview** — `aizuchi overview <dir...>` aggregates multiple `.kanban` directories
+  read-only.
+- **Command palette ⌘K** — switch views, jump to a task by search, create a task, and open settings
+  in one action.
+- **Task detail** — Markdown preview, body editing (conflict detection on save → line-diff prompt),
+  and a timeline of the work log and exchanges (two-way comments).
+- **Warning banner** — surfaces broken frontmatter, duplicate IDs, unregistered members, and invalid
+  config (the board stays up).
+
+## Development
 
 ```bash
-npm install          # 依存インストール
-npm run dev          # 開発: Vite + API を 1 プロセスで起動（http://127.0.0.1:5173 など）
-npm run build        # web を dist/web にビルド + server/shared を dist にコンパイル
-npm run serve        # ビルド済み dist を 1 プロセスで配信（= node dist/bin/aizuchi.js serve）
+npm install          # install dependencies
+npm run dev          # dev: Vite + API in a single process (e.g. http://127.0.0.1:5173)
+npm run build        # build web into dist/web + compile server/shared into dist
+npm run serve        # serve the built dist in one process (= node dist/bin/aizuchi.js serve)
 npm test             # vitest
-npm run typecheck    # tsc（server）+ tsc -p web/tsconfig.json（web）
+npm run typecheck    # tsc (server) + tsc -p web/tsconfig.json (web)
 ```
 
-- 開発時は Vite の `configureServer` に Hono アプリをマウントし、`npm run dev` 一発で SPA と API の
-  両方が立ち上がります（proxy も concurrently も不要）。
-- 別プロジェクトを開発対象にしたい場合は `AIZUCHI_DEV_ROOT=/path/to/project npm run dev`。
+- In development, the Hono app is mounted onto Vite's `configureServer`, so `npm run dev` brings up
+  both the SPA and the API at once (no proxy, no concurrently).
+- To develop against a different target project, use `AIZUCHI_DEV_ROOT=/path/to/project npm run dev`.
 
-## 構成
+## Architecture
 
 ```
-                  ┌──────────── 1 プロセス (Node.js) ────────────┐
- ブラウザ ──HTTP──▶│  静的配信 (dist/web)  REST API   SSE        │
+                  ┌──────────── single process (Node.js) ───────┐
+ browser ──HTTP──▶│  static serve (dist/web)  REST API   SSE    │
  (React SPA)  ◀SSE─│  server/static.ts    server/app.ts events  │──watch/read/write──▶ .kanban/
-                  │           chokidar watcher (server/watcher) │                     (プレーンテキスト)
+                  │           chokidar watcher (server/watcher) │                     (plain text)
                   └────────────────────────────────────────────┘            ▲
-                                                                  AI / 人間が直接編集 or CLI
+                                                          AI / human edit directly or via the CLI
 ```
 
 ```
 aizuchi/
-├── bin/aizuchi.ts    # CLI エントリ（init / serve / task / overview）。dist/bin/aizuchi.js にコンパイル
-├── server/           # Hono アプリ・watcher・静的配信・ファイル I/O
-│   ├── app.ts        #   REST API（board / tasks / events）+ Host 検証 + onError
-│   ├── overview.ts   #   複数 .kanban の read-only 集約（aizuchi overview・既定ポート 5152）
-│   ├── board.ts      #   .kanban 読込・zod 検証・警告生成
-│   ├── watcher.ts    #   chokidar（debounce 200ms）→ SSE
-│   ├── static.ts     #   ビルド済み SPA の配信（トラバーサル拒否）
+├── bin/aizuchi.ts    # CLI entry (init / serve / task / overview). Compiled to dist/bin/aizuchi.js
+├── server/           # Hono app, watcher, static serving, file I/O
+│   ├── app.ts        #   REST API (board / tasks / events) + Host validation + onError
+│   ├── overview.ts   #   read-only aggregation of multiple .kanban (aizuchi overview, default port 5152)
+│   ├── board.ts      #   .kanban loading, zod validation, warning generation
+│   ├── watcher.ts    #   chokidar (200ms debounce) → SSE
+│   ├── static.ts     #   serving the built SPA (traversal rejected)
 │   └── lib/          #   task-file / pinpoint / id / fs-safe / time / git / trash / task-ops
-├── web/              # Vite + React SPA（ビルド成果物を dist/web に同梱）
+├── web/              # Vite + React SPA (build output bundled into dist/web)
 │   └── src/          #   App / useBoard / components / lib
-├── shared/           # task / config の zod スキーマ・型・行 LCS diff（server / web 共有）
-├── templates/        # config.json / claude-rules.md（init が生成）
-└── docs/             # decisions.md ほか
+├── shared/           # zod schemas, types, and line LCS diff for task / config (shared by server / web)
+├── templates/        # config.json / claude-rules.md (generated by init)
+└── docs/             # decisions.md and others
 ```
 
-## データ仕様（抜粋）
+## Data model (excerpt)
 
-- タスク = `.kanban/tasks/<ID>.md`（1 タスク 1 ファイル、**ID＝ファイル名**）。
+- A task = `.kanban/tasks/<ID>.md` (one task per file, **ID = filename**).
 - frontmatter: `id` / `title` / `status` / `assignee` / `created_by` / `priority` / `labels` /
-  `blocked_type` / `blocked_reason` / `depends_on` / `milestone` / `created` / `updated`。
-- `status`: `proposed` / `backlog` / `todo` / `in_progress` / `pending` / `done`。
-- 日時は ISO 8601（タイムゾーン付き、例: `2026-06-10T10:00:00+09:00`）。UTC へ変換しません。
-- 設定は `.kanban/config.json`（プロジェクト名・ID 接頭辞・ポート・メンバー・カラム・マイルストーン・
-  タスクテンプレート・保存済みビュー・停滞閾値・言語 ほか）。設定ゼロでも既定値で動作します。
-
-各フィールドの enum 値・必須条件など完全な frontmatter スキーマは、`aizuchi init` が `CLAUDE.md` に追記する運用規約（frontmatter スキーマ表）に記載されます。init 後すぐ手元で確認できます。
-
-## 手動確認チェックリスト（受け入れ基準 / DoD）
-
-`npm run build` 後に対象プロジェクトで `node dist/bin/aizuchi.js init` → `... serve` を実行し、ブラウザで確認します。
-
-- [ ] **init**: `node bin/aizuchi.js init` で `.kanban/`（config.json・tasks/・archive/・README）が生成され、
-      CLAUDE.md にマーカーコメント区切りで運用規約が追記される（既存があれば末尾追記、再実行は同区間のみ置換、
-      既存 `.kanban/` があれば安全に中断）。
-- [ ] **serve**: `node bin/aizuchi.js serve` で `http://127.0.0.1:5151` にボードが表示される。127.0.0.1 以外に
-      バインドしない。
-- [ ] **起票**: 追加モーダルからタスクを作成すると `tasks/TASK-00X.md` が生成され、ID が連番になる
-      （起票者は members から選択、その ID が `created_by` に入る）。
-- [ ] **D&D**: カラム移動で frontmatter の `status` / `updated` だけが変わる（`git diff` で本文保全を確認）。
-- [ ] **ライブ反映**: エディタで直接タスクファイルを書き換えると 1 秒以内にボードへ反映される。
-- [ ] **保留表示**: pending カードに保留種別（色分けバッジ）と理由が表示され、in_progress カードに
-      「最終更新 ◯分前」が表示される。
-- [ ] **警告**: frontmatter を壊したファイルを置くと警告バナーに表示され、ボード自体は落ちない。
-- [ ] **詳細**: タスク詳細でプレビュー・編集・作業ログのタイムラインが使える。保存時に外部変更と競合したら
-      上書き確認（差分提示）が出る。
-- [ ] **アーカイブ / ごみ箱**: done をアーカイブ → アーカイブビューから復元できる。破壊的書換の前に
-      `.kanban/.trash/` へ退避され、ごみ箱から復元できる。
-- [ ] **ネットワーク**: 動作中、外部へのネットワーク通信が一切発生しない。
-- [ ] **終了**: ブラウザでボードを開いたまま `Ctrl+C` で serve が速やかに終了する。
-- [ ] **再現性**: 本 README の手順だけで第三者が環境構築〜起動まで再現できる。
-
-## アクセシビリティ
-
-キーボードとスクリーンリーダーでの操作を考慮しています。
-
-- **キーボード操作**: フォームやボタンは Tab で移動・操作できます。コマンドパレット（⌘K / Ctrl+K）から
-  ビュー切替・タスク検索ジャンプ・起票・設定をキーボードだけで実行できます。
-- **キーボードでのカード移動**: カードにフォーカスして **Space で掴み**、矢印キーでカラム間を移動、
-  再度 Space で確定（Enter はカード詳細を開く）。ポインタ D&D と同じ status 更新経路・Pending 行きは保留ダイアログを起動。
-- **モーダル**: 開いた時に内部へフォーカスを移し、Tab / Shift+Tab はダイアログ内をループ（focus trap）、
-  Escape で閉じ、閉じたら元の要素へフォーカスを戻します。
-- **ARIA / 役割**: カラムやカード、ツールバー、ダイアログに `role` と `aria-label` を付与しています。
-
-## 技術スタック
+  `blocked_type` / `blocked_reason` / `depends_on` / `milestone` / `created` / `updated`.
+- `status`: `proposed` / `backlog` / `todo` / `in_progress` / `pending` / `done`.
+- Timestamps are ISO 8601 (with timezone, e.g. `2026-06-10T10:00:00+09:00`). They are not converted
+  to UTC.
+- Configuration lives in `.kanban/config.json` (project name, ID prefix, port, members, columns,
+  milestones, task template, saved views, stale thresholds, language, and more). It works on
+  defaults with zero configuration.
+
+The complete frontmatter schema — including each field's enum values and required conditions — is
+recorded in the operating rules (the frontmatter schema table) that `aizuchi init` appends to
+`CLAUDE.md`. You can check it right after init.
+
+## Manual verification checklist (acceptance criteria / DoD)
+
+After `npm run build`, run `node dist/bin/aizuchi.js init` → `... serve` in the target project and
+verify in the browser.
+
+- [ ] **init**: `node bin/aizuchi.js init` generates `.kanban/` (config.json, tasks/, archive/,
+      README) and appends the operating rules to CLAUDE.md inside marker comments (append at the end
+      if one exists, re-run replaces only that section, stop safely if `.kanban/` already exists).
+- [ ] **serve**: `node bin/aizuchi.js serve` shows the board at `http://127.0.0.1:5151`. It does not
+      bind to anything other than 127.0.0.1.
+- [ ] **create**: creating a task from the add modal generates `tasks/TASK-00X.md` with a sequential
+      ID (the creator is chosen from members, and that ID goes into `created_by`).
+- [ ] **drag & drop**: moving between columns changes only the `status` / `updated` frontmatter
+      (confirm the body is preserved with `git diff`).
+- [ ] **live updates**: editing a task file directly in your editor is reflected on the board within
+      a second.
+- [ ] **block display**: a pending card shows the block kind (color-coded badge) and reason, and an
+      in_progress card shows "last updated N minutes ago".
+- [ ] **warnings**: placing a file with broken frontmatter shows up in the warning banner without
+      crashing the board.
+- [ ] **detail**: the task detail offers preview, editing, and a work-log timeline. If a save
+      conflicts with an external change, an overwrite confirmation (with a diff) appears.
+- [ ] **archive / trash**: archive a done task → restore it from the archive view. Before a
+      destructive rewrite the old version is backed up to `.kanban/.trash/` and can be restored from
+      the trash.
+- [ ] **network**: no outbound network communication occurs at all while running.
+- [ ] **shutdown**: with the board open in the browser, `Ctrl+C` stops serve promptly.
+- [ ] **reproducibility**: a third party can go from setup to launch using only this README.
+
+## Accessibility
+
+Keyboard and screen-reader operation is taken into account.
+
+- **Keyboard operation** — forms and buttons can be reached and operated with Tab. The command
+  palette (⌘K / Ctrl+K) lets you switch views, jump to a task by search, create a task, and open
+  settings entirely from the keyboard.
+- **Moving cards with the keyboard** — focus a card, **grab it with Space**, move between columns
+  with the arrow keys, and confirm with Space again (Enter opens the card detail). It uses the same
+  status-update path as pointer drag & drop, and moving to Pending triggers the block dialog.
+- **Modals** — focus moves inside on open, Tab / Shift+Tab loop within the dialog (focus trap),
+  Escape closes it, and focus returns to the original element after closing.
+- **ARIA / roles** — columns, cards, the toolbar, and dialogs carry `role` and `aria-label`.
+
+## Tech stack
 
 Node.js 20.1+ / Hono + @hono/node-server / chokidar / SSE / React 18 + TypeScript + Vite /
-@dnd-kit / react-markdown + remark-gfm / gray-matter / zod / CSS Modules / vitest。
+@dnd-kit / react-markdown + remark-gfm / gray-matter / zod / CSS Modules / vitest.
+
+### Dependencies added beyond the core stack, and why
+
+- **@hono/node-server** — runs Hono on the Node runtime and statically serves the built SPA.
+- **js-yaml (+ @types/js-yaml)** — injects the `JSON_SCHEMA` engine into gray-matter so that
+  timestamps with `+09:00` round-trip as strings instead of being turned into `Date` (avoids the
+  transitive dependency on gray-matter's bundled, older 3.x).
+- **@vitejs/plugin-react** — enables React (JSX / Fast Refresh) in Vite.
+- **@dnd-kit/utilities** — part of the @dnd-kit family; assists with the D&D CSS transform.
+- **tsx** — runs the TypeScript server directly during development (production uses the compiled JS
+  in dist).
+- **typescript / vitest / @types/\*** — the foundation for type safety and testing.
 
-### 主要スタックに追加した依存とその理由
+## Repository
 
-- **@hono/node-server** — Hono を Node ランタイムで起動し、ビルド済み SPA を静的配信するため
-- **js-yaml (+ @types/js-yaml)** — gray-matter に `JSON_SCHEMA` エンジンを注入し、`+09:00` 付き日時を Date 化せず文字列のまま往復させるため（gray-matter 内蔵の旧 3.x に transitive 依存しない）
-- **@vitejs/plugin-react** — Vite で React（JSX / Fast Refresh）を使うため
-- **@dnd-kit/utilities** — @dnd-kit ファミリ。D&D の CSS transform 補助
-- **tsx** — 開発時に TypeScript サーバーを直接実行するため（本番は dist のコンパイル済み JS を使用）
-- **typescript / vitest / @types/\*** — 型安全とテストの基盤
+- npm package: `aizuchi`
+- Source & issues: <https://github.com/megaphone-tokyo/AIzuchi>
 
-## ライセンス
+## License
 
 MIT

package/dist/bin/aizuchi.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { serve } from '@hono/node-server';
-import { DEFAULT_OVERVIEW_PORT, DEFAULT_PORT } from '../shared/schema.js';
+import { DEFAULT_OVERVIEW_PORT, DEFAULT_PORT, PORT_FALLBACK_ATTEMPTS } from '../shared/schema.js';
 import { analyzeCriticalPath } from '../shared/critical-path.js';
 import { createApp } from '../server/app.js';
 import { loadArchive, loadBoard, loadConfig } from '../server/board.js';
@@ -16,7 +16,7 @@ import { startWatcher } from '../server/watcher.js';
 /**
  * AIzuchi CLI (要件 §4.3)。
  * - init : .kanban/ を生成し、CLAUDE.md へ運用規約をマーカー区切りで追記する (N-9: 冪等)
- * - serve: 127.0.0.1 限定でボードを起動する (--port > config > 5151)
+ * - serve: 127.0.0.1 限定でボードを起動する (--port > config > 5151。--port 未指定なら使用中時に次の空きへ自動フォールバック)
  * - overview: 複数 .kanban の read-only 集約を起動する (--port > 5152、波 VII)
  */
 export const MARKER_BEGIN = '<!-- aizuchi:begin -->';
@@ -159,28 +159,65 @@ export async function runServe(options) {
         // .kanban が symlink / 不在: cleanup を skip (containment 外の削除はしない)
     }
     const { config } = await loadConfig(cwd);
-    const port = options.port ?? config.port ?? DEFAULT_PORT;
+    // --port を明示したらそのポートに固定 (使用中ならエラー終了)。明示しない場合は
+    // config.port → 既定 5151 を起点に、使用中なら順に次の空きへフォールバックする
+    // (複数プロジェクトを同時に serve してもポート衝突で止まらないように)。
+    // 起点は毎回同じで状態を保存しないため、次回起動時に起点が空いていれば必ず起点で起動する。
+    const explicitPort = options.port !== undefined;
+    const basePort = options.port ?? config.port ?? DEFAULT_PORT;
+    const maxAttempts = explicitPort ? 1 : PORT_FALLBACK_ATTEMPTS;
     const bus = createEventBus();
     const { app } = createApp({ projectRoot: cwd, bus });
     attachStaticAssets(app, path.join(packageRoot(), 'dist', 'web'));
     const watcher = startWatcher({ kanbanDir, bus });
-    const { server, boundPort } = await new Promise((resolve, reject) => {
-        // 127.0.0.1 限定でバインドする (N-1)。0.0.0.0 や LAN IP への変更手段は提供しない。
+    // 1 ポートぶんの listen 試行。成功で {server, boundPort}、EADDRINUSE で 'busy'、その他は reject。
+    // 127.0.0.1 限定でバインドする (N-1)。フォールバックで変えるのはポート番号のみ・host は固定。
+    const tryListen = (candidate) => new Promise((resolve, reject) => {
+        let settled = false;
         // info.port は実際にバインドされたポート (port=0 のときは OS が選んだ番号が入る)
-        const created = serve({ fetch: app.fetch, port, hostname: '127.0.0.1' }, (info) => resolve({ server: created, boundPort: info.port }));
+        const created = serve({ fetch: app.fetch, port: candidate, hostname: '127.0.0.1' }, (info) => {
+            settled = true;
+            resolve({ server: created, boundPort: info.port });
+        });
         created.on('error', (error) => {
+            if (settled)
+                return; // listen 成功後の実行時エラーはここでは扱わない
             if (error.code === 'EADDRINUSE') {
-                // 自動でポートを変えず、明確なエラーで終了する (決定済み)
-                reject(new Error(`ポート ${port} は使用中です。--port <番号> か .kanban/config.json の port で変更してください`));
+                try {
+                    created.close();
+                }
+                catch {
+                    /* バインド失敗した server の close 失敗は無視 */
+                }
+                resolve('busy');
             }
             else {
                 reject(error);
             }
         });
-    }).catch(async (error) => {
-        await watcher.close();
-        throw error;
     });
+    let listened = null;
+    for (let i = 0; i < maxAttempts; i++) {
+        const result = await tryListen(basePort + i).catch(async (error) => {
+            await watcher.close();
+            throw error; // EADDRINUSE 以外 (権限不足など) は即終了
+        });
+        if (result !== 'busy') {
+            listened = result;
+            break;
+        }
+    }
+    if (listened === null) {
+        await watcher.close();
+        if (explicitPort) {
+            throw new Error(`ポート ${basePort} は使用中です。別の --port <番号> を指定するか、起動中の AIzuchi を終了してください`);
+        }
+        throw new Error(`空きポートが見つかりませんでした (${basePort}〜${basePort + maxAttempts - 1} はすべて使用中)。--port <番号> で指定してください`);
+    }
+    const { server, boundPort } = listened;
+    if (!explicitPort && boundPort !== basePort) {
+        log(`ポート ${basePort} は使用中のため ${boundPort} で起動しました`);
+    }
     log(`AIzuchi: http://127.0.0.1:${boundPort} (project: ${config.projectName})`);
     log('終了するには Ctrl+C');
     return {