aizuchi 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,69 @@
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-06-17
+
+資料 (ドキュメント) をボード上で作って育てられるようにし、依存・優先度のその場編集や AI 参加者の状態把握を加えたリリース。
+
+### Added (追加)
+
+- **関連資料の作成・編集・削除**: これまで読むだけだった「関連資料」を、ボード上で新規作成・編集・削除できるように。
+  保存先は新しい設定 `docsWriteDirs` に列挙したディレクトリのみ (既定は空 = 機能オフ・読取専用の `docsDirs` と分離)。
+  保存はアトミック (一時ファイル→rename)、上書きは保存時刻 (mtime) 比較で競合を検知、削除は `.kanban/.trash` へ退避して
+  から消す (復元可能)。保存ダイアログで親フォルダ選択 + 新規フォルダ作成 + ファイル名指定。資料から直接タスクを起票する
+  導線付き。パスは正規化 + symlink 解決後にプロジェクト配下のみ許可 (パストラバーサル対策)。
+- **資料エディタのシンタックスハイライト**: Markdown を編集中、見出し・太字・コード・リスト・リンクなどが色分け表示
+  されるように。依存ライブラリを足さない自前実装で、ハイライトは本文を一切書き換えない。
+- **資料エディタの横並び表示**: 編集とプレビューをタブ切替だけでなく **横に並べて同時に** 見られるように (既定)。
+  入力に追従するライブプレビュー付き。画面が狭いときは自動で縦積みに切り替わる。全幅の編集 / プレビューも選べる。
+- **依存・優先度のその場編集**: タスク詳細の「メタ」タブで depends_on (依存) と priority をクリック操作で編集できるように。
+  クリティカルパスを見ながらその場で依存関係や優先度を組み替えられる。保存は既存の競合検知に乗る。
+- **AI オンボーディング診断パネル**: 参加している AI メンバーごとに、タスクの書式ミス・未登録メンバーの使用・設定の問題を
+  「直し方」付きで一覧表示する読取専用パネル。AI が規約どおりに参加できているかを人間が把握できる。
+- **設定画面でのディレクトリ編集**: 資料の読取先 (`docsDirs`) と書込先 (`docsWriteDirs`) を設定画面の GUI から
+  追加・削除できるように。これまで config.json を手で編集する必要があった資料機能の有効化が、画面から行える。
+- キーボードショートカットのヘルプ (`?`) に **「AI への導入指示をコピー」ボタン**を追加。AI エージェント
+  (Claude 等) にこのプロジェクトへ AIzuchi 経由で参加してもらうための指示文を、プロジェクト名・AI メンバー ID・
+  起票モード (free / proposal) を反映してワンクリックでコピーできる。新規プロジェクトのオンボーディングが速くなる。
+- **`serve` のポート自動フォールバック**: 起点ポート (既定 `5151`) が使用中のとき、自動で次の空きポート
+  (`5152`, `5153`…) を探して起動するように。複数プロジェクトを同時に `serve` してもポート衝突で止まらない。
+  起点と違うポートで起動した場合はその旨をログに出す。起点は毎回 `5151` から試すため、次回起動時に空いていれば
+  `5151` に戻る (状態は保存しない)。`--port` を明示した場合のみ従来どおり固定 (使用中ならエラー終了)。
+  バインド先は `127.0.0.1` 固定のまま変えない (N-1)。
+
+### Changed (変更)
+
+- マイルストーンの「対応履歴」の行で、タイトル列を固定幅にして**本文 (サマリ) の開始位置を全行で揃える**ように。
+  これまではタイトルの文字数ぶんだけ幅が変わり本文の左端がバラついていた。収まらないタイトルは `…` で省略し、
+  全文は hover (title 属性) とクリックで確認できる。マイルストーン所属タスク一覧 (status を出す行) は対象外。
+- アクセシビリティ改善: いくつかの入力欄 (コメント投稿者・コメント入力・メンバー種別・詳細 JSON エディタ) に
+  適切なラベル (aria-label) を付与し、ブラウザ開発者ツールのフォーム警告を解消。
+
+## [0.4.0] - 2026-06-16
+
+「今どうなっているか・次に何をすべきか」の見通しと、堅牢性・操作性を高めるリリース。
+
+### Added (追加)
+
+- **ホーム「次の一手」ビュー**（既定の最初のタブ）: 判断待ち・停滞・クリティカルパスの律速・WIP 超過・新着を
+  1 画面に集約し、開いた瞬間に「今プロジェクトを止めているもの」「次に着手すべきタスク」が分かる。
+  既存の集計ロジックを束ねるだけで、新しい保存先や通信は増やさない。タブの並べ替え・非表示で従来どおり
+  ボードを最初のタブに戻せる。
+- **タスク詳細のタイムラインタブ**: 作業ログ・やりとり・コミットを 1 本の時系列にまとめて表示し、
+  「このタスクで何がいつ起きたか」を一目で追える。
+- **やりとり / 作業ログ / タイムラインの `@member` ハイライト**: 登録メンバー宛のメンションを強調表示。
+  やりとりタブでは投稿者（=あなた）宛のメンションをさらに強調する。
+- **AI 用 CLI に読取系コマンドを追加**（read-only）: `aizuchi task list`（一覧・`--status` / `--assignee` 絞り込み）、
+  `task show <id>`（1 タスクの詳細）、`task next`（依存が解決済みで着手できるタスクをクリティカルパス優先で提示）。
+  AI が「今の状態」「次の一手」をファイル経由で引ける。いずれも `--json` 対応。
+- **キーボードショートカットのヘルプ**: `?` キーまたはヘッダーの「?」ボタンで、⌘K・カードの移動（Space で掴む /
+  矢印で移動）・Enter で詳細・Esc などの一覧を表示。
+
+### Changed (変更)
+
+- 各ビューを Error Boundary で隔離し、1 つのビューの表示エラーがアプリ全体を白画面にしないように
+  （他のタブへ切り替える / 再試行で復帰できる）。
+
 ## [0.3.0] - 2026-06-16
 
 UI を大幅に刷新し、協働ループ・自己診断・グローバル設定編集などを追加した節目のリリース。
@@ -115,7 +178,8 @@ UI をデザイントークン体系で刷新しました。
 - **セキュリティ**: ローカル限定 (127.0.0.1)・書込パス許可リスト + symlink / トラバーサル拒否・
   アトミック書込 + mtime 競合検知・秘匿情報のログ非出力・git 履歴連携 (read-only)。
 
-[Unreleased]: https://github.com/megaphone-tokyo/AIzuchi/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/megaphone-tokyo/AIzuchi/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/megaphone-tokyo/AIzuchi/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/megaphone-tokyo/AIzuchi/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/megaphone-tokyo/AIzuchi/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/megaphone-tokyo/AIzuchi/releases/tag/v0.1.0

package/README.md

@@ -88,9 +88,10 @@ UI 表示言語は英語 / 日本語（en / ja・既定 en）を切り替えら
   マーカー区切りで追記。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` を提供。
-  既存のスキーマ検証・採番直列化・行置換検証を再利用します（生ファイル編集も従来どおり可）。
+- **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` 対応）。
 
 ### そのほか
 

package/dist/bin/aizuchi.js

@@ -4,9 +4,10 @@ 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 { loadConfig } from '../server/board.js';
+import { loadArchive, loadBoard, loadConfig } from '../server/board.js';
 import { createEventBus } from '../server/events.js';
 import { cleanupStaleTmpFiles, resolveKanbanReal, writeFileAtomic } from '../server/lib/fs-safe.js';
 import { createOverviewApp } from '../server/overview.js';
@@ -15,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 -->';
@@ -158,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 {
@@ -473,8 +511,117 @@ export async function runTaskCli(argv, io = {
                 const view = await ops.appendComment(positional[0] ?? '', opts.get('member') ?? 'claude', positional[1] ?? '');
                 return emit(view, `コメント追記: ${view.frontmatter.id}`);
             }
+            // --- 読取系 (read-only。AI が「今の状態」「次の一手」をファイル経由で引ける) ---
+            case 'list': {
+                // アクティブなタスク一覧。--status / --assignee で絞り込み。書込なし
+                const board = await loadBoard(root);
+                const statusFilter = opts.get('status');
+                const assigneeFilter = opts.get('assignee');
+                const rows = board.tasks
+                    .filter((t) => statusFilter === undefined || t.frontmatter.status === statusFilter)
+                    .filter((t) => assigneeFilter === undefined || t.frontmatter.assignee === assigneeFilter)
+                    .map((t) => ({
+                    id: t.frontmatter.id,
+                    status: t.frontmatter.status,
+                    assignee: t.frontmatter.assignee,
+                    priority: t.frontmatter.priority,
+                    title: t.frontmatter.title,
+                    labels: t.frontmatter.labels,
+                }))
+                    .sort((a, b) => a.id.localeCompare(b.id, 'en', { numeric: true }));
+                if (json) {
+                    io.out(JSON.stringify(rows));
+                }
+                else if (rows.length === 0) {
+                    io.out('(該当タスクなし)');
+                }
+                else {
+                    for (const r of rows)
+                        io.out(`${r.id}\t${r.status}\t${r.assignee ?? '-'}\t${r.title}`);
+                }
+                return 0;
+            }
+            case 'show': {
+                // 1 タスクの詳細 (frontmatter 要約 + 本文)。アクティブ → 無ければ archive を探す
+                const id = positional[0] ?? '';
+                if (id === '') {
+                    io.err(json ? JSON.stringify({ error: 'id required', code: 'invalid_input' }) : 'show には <id> が必要です');
+                    return 1;
+                }
+                const board = await loadBoard(root);
+                const found = board.tasks.find((t) => t.frontmatter.id === id);
+                if (found !== undefined) {
+                    if (json) {
+                        io.out(JSON.stringify(found));
+                    }
+                    else {
+                        const f = found.frontmatter;
+                        io.out(`${f.id}  [${f.status}]  ${f.title}`);
+                        io.out(`assignee: ${f.assignee ?? '-'}  priority: ${f.priority}  labels: ${f.labels.join(', ') || '-'}`);
+                        if (f.depends_on.length > 0)
+                            io.out(`depends_on: ${f.depends_on.join(', ')}`);
+                        if (f.status === 'pending')
+                            io.out(`blocked: ${f.blocked_type ?? '-'} — ${f.blocked_reason ?? '-'}`);
+                        io.out('');
+                        io.out(found.body.trim());
+                    }
+                    return 0;
+                }
+                const archived = (await loadArchive(root)).find((a) => a.id === id);
+                if (archived !== undefined) {
+                    if (json) {
+                        io.out(JSON.stringify({ ...archived, archived: true }));
+                    }
+                    else {
+                        io.out(`${archived.id}  [archived]${archived.title ? `  ${archived.title}` : ''}`);
+                        io.out('');
+                        io.out((archived.body ?? '').trim());
+                    }
+                    return 0;
+                }
+                io.err(json ? JSON.stringify({ error: 'not found', code: 'not_found', id }) : `タスクが見つかりません: ${id}`);
+                return 2;
+            }
+            case 'next': {
+                // 「次に着手できるタスク」= 未完了かつ依存が全て解決済み (active な先行依存なし) の
+                // backlog/todo/in_progress。クリティカルパス上を優先表示する。書込なし
+                const board = await loadBoard(root);
+                const active = board.tasks.filter((t) => t.frontmatter.status !== 'done');
+                const cp = analyzeCriticalPath(active.map((t) => ({ id: t.frontmatter.id, dependsOn: t.frontmatter.depends_on })));
+                const onCp = new Set(cp.criticalPath);
+                const activeIds = new Set(active.map((t) => t.frontmatter.id));
+                const ACTIONABLE = new Set(['backlog', 'todo', 'in_progress']);
+                const ready = active
+                    .filter((t) => ACTIONABLE.has(t.frontmatter.status) &&
+                    t.frontmatter.depends_on.every((d) => !activeIds.has(d)))
+                    .map((t) => ({
+                    id: t.frontmatter.id,
+                    status: t.frontmatter.status,
+                    title: t.frontmatter.title,
+                    onCriticalPath: onCp.has(t.frontmatter.id),
+                }))
+                    .sort((a, b) => {
+                    if (a.onCriticalPath !== b.onCriticalPath)
+                        return a.onCriticalPath ? -1 : 1;
+                    return a.id.localeCompare(b.id, 'en', { numeric: true });
+                });
+                if (json) {
+                    io.out(JSON.stringify({ ready, criticalPath: cp.criticalPath, hasCycle: cp.cycleNodes.length > 0 }));
+                    return 0;
+                }
+                if (cp.cycleNodes.length > 0)
+                    io.out(`⚠ 依存に循環があります: ${cp.cycleNodes.join(', ')}`);
+                if (ready.length === 0) {
+                    io.out('着手可能なタスクはありません (全て完了 / 依存待ち / ブロック中)');
+                    return 0;
+                }
+                io.out('次に着手できるタスク (依存解決済み):');
+                for (const r of ready)
+                    io.out(`- ${r.id} (${r.status})${r.onCriticalPath ? ' ★CP' : ''}  ${r.title}`);
+                return 0;
+            }
             default:
-                io.err('task サブコマンド: add / move <id> <status> / done <id> / block <id> --type --reason / revise <id> [--reason "..."] / log <id> "msg" / comment <id> "msg"');
+                io.err('task サブコマンド: add / move <id> <status> / done <id> / block <id> --type --reason / revise <id> [--reason "..."] / log <id> "msg" / comment <id> "msg" / list [--status S] [--assignee M] / show <id> / next');
                 return 1;
         }
     }

package/dist/server/app.js

@@ -10,7 +10,8 @@ import { loadArchive, loadBoard, loadConfig, loadTaskView } from './board.js';
 import { createEventBus } from './events.js';
 import { allocateNextId, createSerialQueue } from './lib/id.js';
 import { assertDirInsideKanban, collectKanbanFilesNoSymlink, FileExistsError, PathValidationError, readKanbanFile, resolveKanbanReal, safeWriteFile, statKanbanFile, } from './lib/fs-safe.js';
-import { buildDocsTree, readDoc } from './lib/docs.js';
+import { buildDocsTree, buildDocsWriteTree, deleteDoc, readDoc, writeDoc } from './lib/docs.js';
+import { assertRelatedDocsAllowed } from './lib/related-docs-validate.js';
 import { findCommitsForTask } from './lib/git.js';
 import { buildCatalog, buildFileTree, buildGlobalCatalog, fileMtime, globalFileMtime, readConfigFile, readGlobalConfigFile, saveConfigFile, saveGlobalConfigFile, } from './lib/files.js';
 import { applyPinpointPatch, renameTaskId, replaceDependsOnId, replaceMemberKeys, verifyMemberRename, verifyPinpointResult, verifyRename, } from './lib/pinpoint.js';
@@ -75,7 +76,7 @@ export function applySecurityMiddleware(app) {
     // GET は読出専用 (CORS ヘッダ無しでクロスオリジン読出不可) なので対象外。
     app.use('/api/*', async (c, next) => {
         const method = c.req.method;
-        if (method === 'POST' || method === 'PUT' || method === 'PATCH') {
+        if (method === 'POST' || method === 'PUT' || method === 'PATCH' || method === 'DELETE') {
             const contentType = c.req.header('content-type') ?? '';
             // "application/json" / "application/json; charset=utf-8" を許可。それ以外は 415
             const mediaType = contentType.split(';')[0].trim().toLowerCase();
@@ -223,6 +224,17 @@ export function createApp(options) {
         if (violations.length > 0) {
             return c.json({ error: violations.join(' / ') }, 400);
         }
+        // 波 VIII: related_docs は docsDirs / docsWriteDirs 配下の妥当な .md 相対パスのみ受け付ける
+        // (frontmatter に保存して良い参照値かの検証。読取時の symlink/TOCTOU 防御は docs.ts が担保)
+        if (input.data.related_docs !== undefined && input.data.related_docs.length > 0) {
+            try {
+                assertRelatedDocsAllowed(projectRoot, config, input.data.related_docs);
+            }
+            catch (error) {
+                const message = error instanceof PathValidationError ? error.message : 'related_docs が不正です';
+                return c.json({ error: message }, 400);
+            }
+        }
         // 走査 → 採番 → 書込 をアトミックに直列化する (同時起票の ID 重複防止)。
         // 書込は排他作成 (exclusive) にし、採番後の窓で AI が同 ID を直書きしていた場合は
         // 上書きせず再採番 retry する (N-3: POST が外部データを silent 上書きするのを防ぐ)
@@ -239,6 +251,7 @@ export function createApp(options) {
                     created_by: input.data.created_by,
                     priority: input.data.priority ?? 'medium',
                     labels: input.data.labels ?? [],
+                    related_docs: input.data.related_docs,
                     blocked_type: null,
                     blocked_reason: null,
                     created: now,
@@ -1120,6 +1133,85 @@ export function createApp(options) {
             throw error;
         }
     });
+    // GET /api/docs/write-tree — docsWriteDirs 配下の .md ツリー (保存先フォルダ選択 UI 用・symlink 非追従)
+    app.get('/api/docs/write-tree', async (c) => {
+        const { config } = await loadConfig(projectRoot);
+        return c.json({ trees: await buildDocsWriteTree(projectRoot, config) });
+    });
+    // POST /api/docs — 資料を新規作成 (exclusive)。親フォルダ未作成なら作成する。既存は 409。
+    app.post('/api/docs', async (c) => {
+        const body = (await c.req.json().catch(() => null));
+        if (body === null || typeof body.path !== 'string' || body.path === '' || typeof body.content !== 'string') {
+            return c.json({ error: 'path (文字列) と content (文字列) が必要です' }, 400);
+        }
+        const relPath = body.path;
+        const content = body.content;
+        const { config } = await loadConfig(projectRoot);
+        return enqueue(async () => {
+            try {
+                const result = await writeDoc(projectRoot, config, relPath, content, 'create');
+                return c.json(result, 201);
+            }
+            catch (error) {
+                if (error instanceof FileExistsError)
+                    return c.json({ error: '同じパスの資料が既に存在します' }, 409);
+                if (error instanceof PathValidationError)
+                    return c.json({ error: error.message }, 403);
+                throw error;
+            }
+        });
+    });
+    // PUT /api/docs?path=... — 資料を上書き保存 (mtime 厳密比較で競合検知)。範囲外 403 / drift 409。
+    app.put('/api/docs', async (c) => {
+        const relPath = c.req.query('path');
+        if (relPath === undefined || relPath === '') {
+            return c.json({ error: 'path クエリが必要です' }, 400);
+        }
+        const body = (await c.req.json().catch(() => null));
+        if (body === null || typeof body.content !== 'string' || typeof body.baseMtimeMs !== 'number') {
+            return c.json({ error: 'content (文字列) と baseMtimeMs (数値) が必要です' }, 400);
+        }
+        const content = body.content;
+        const baseMtimeMs = body.baseMtimeMs;
+        const { config } = await loadConfig(projectRoot);
+        return enqueue(async () => {
+            try {
+                const result = await writeDoc(projectRoot, config, relPath, content, 'overwrite', baseMtimeMs);
+                if ('conflict' in result) {
+                    return c.json({ error: '外部で変更されています', serverContent: result.conflict.serverContent, serverMtimeMs: result.conflict.serverMtimeMs }, 409);
+                }
+                return c.json(result);
+            }
+            catch (error) {
+                if (error instanceof PathValidationError)
+                    return c.json({ error: error.message }, 403);
+                if (error.code === 'ENOENT')
+                    return c.json({ error: '資料が見つかりません' }, 404);
+                throw error;
+            }
+        });
+    });
+    // DELETE /api/docs?path=... — 資料を削除 (unlink 前に .kanban/.trash へ退避)。不在 404 / 範囲外 403。
+    app.delete('/api/docs', async (c) => {
+        const relPath = c.req.query('path');
+        if (relPath === undefined || relPath === '') {
+            return c.json({ error: 'path クエリが必要です' }, 400);
+        }
+        const { config } = await loadConfig(projectRoot);
+        return enqueue(async () => {
+            try {
+                const result = await deleteDoc(projectRoot, config, relPath);
+                return c.json({ path: result.path, deleted: true });
+            }
+            catch (error) {
+                if (error instanceof PathValidationError)
+                    return c.json({ error: error.message }, 403);
+                if (error.code === 'ENOENT')
+                    return c.json({ error: '資料が見つかりません' }, 404);
+                throw error;
+            }
+        });
+    });
     // ---------------------------------------------------------------------
     // GET /api/tasks/:id/commits — タスク ID を含む git コミット (S-1・read-only)
     // ID をパスから取得 → taskIdSchema で検証 → git.ts が更に厳格バリデーション + execFile (シェル非経由)。

package/dist/server/lib/docs.js

@@ -1,6 +1,7 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import { isSecretPath, isStrictlyInside, PathValidationError, readFileNoFollow, sanitizeConfigDirEntries, } from './fs-safe.js';
+import { isSecretPath, isStrictlyInside, PathValidationError, readFileNoFollow, resolveKanbanReal, safeWriteFile, sanitizeConfigDirEntries, } from './fs-safe.js';
+import { snapshotToTrash, DEFAULT_TRASH_KEEP } from './trash.js';
 /**
  * 関連資料 (波 VIII) の読取専用ファイル I/O。
  * config.docsDirs に列挙されたディレクトリ配下の .md のみを対象にする。
@@ -23,6 +24,15 @@ function effectiveDocsDirs(root, config) {
     const kanbanDir = path.join(root, '.kanban');
     return sanitizeConfigDirEntries(root, config.docsDirs).filter((dir) => dir !== kanbanDir && !isStrictlyInside(kanbanDir, dir) && !isSecretPath(dir));
 }
+/**
+ * config.docsWriteDirs を root 配下の有効な書込先ディレクトリ集合 (絶対パス) に正規化する。
+ * effectiveDocsDirs (読取) と同一ロジック: root 自身 / root 外 / .kanban 配下 / 秘匿パスを除外する
+ * (読取と書込で許可リストを分離するため別関数。docsWriteDirs 既定は空 = 書込オフ)。
+ */
+function effectiveDocsWriteDirs(root, config) {
+    const kanbanDir = path.join(root, '.kanban');
+    return sanitizeConfigDirEntries(root, config.docsWriteDirs).filter((dir) => dir !== kanbanDir && !isStrictlyInside(kanbanDir, dir) && !isSecretPath(dir));
+}
 /** 要求された相対パスが docsDirs 配下の .md であることを検証し、正規化済み絶対パスを返す */
 export async function resolveDocPath(projectRoot, config, requestedRelPath) {
     const root = path.resolve(projectRoot);
@@ -87,11 +97,12 @@ export async function readDoc(projectRoot, config, relPath) {
     // R14-4: resolveDocPath の lstat (symlink 拒否) と readFile の間で対象が symlink に差し替わる
     // TOCTOU 窓を O_NOFOLLOW で塞ぐ (対象が symlink なら open が ELOOP で失敗する)。
     const content = await readFileNoFollow(absPath);
+    const mtimeMs = (await fs.lstat(absPath)).mtimeMs;
     // absPath は realpath ベースの canonical のため、相対化も realpath 済み root を基準にする
     // (macOS の /var → /private/var のような root 側 symlink で相対パスがずれないように)
     const root = path.resolve(projectRoot);
     const rootReal = await fs.realpath(root).catch(() => root);
-    return { path: path.relative(rootReal, absPath), content };
+    return { path: path.relative(rootReal, absPath), content, mtimeMs };
 }
 /**
  * docsDirs 配下の .md ファイルツリーを構築する。buildFileTree (files.ts) と同じ手動再帰で
@@ -152,3 +163,165 @@ async function buildDocsNode(root, absPath) {
     }
     return null;
 }
+/**
+ * target の祖先のうち realpath できる最も近いものと、未作成 segment 列を返す
+ * (config-paths.ts の同名非 export 関数と同型。docs 書込でも親未作成を許すために複製・LEARN#8b N=2 で defer)。
+ * 未作成 segment は実体が無く symlink になり得ないため、containment 判定は実在祖先の realpath で足りる。
+ */
+async function resolveNearestExistingAncestor(target) {
+    const missing = [];
+    let cur = target;
+    for (;;) {
+        try {
+            return { real: await fs.realpath(cur), missing };
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                throw new PathValidationError('親ディレクトリが解決できません');
+            missing.unshift(path.basename(cur));
+            cur = parent;
+        }
+    }
+}
+/**
+ * 書込要求の相対パスが docsWriteDirs 配下の .md であることを検証し、正規化済み canonical と rootReal を返す
+ * (resolveDocPath の write 版)。読取と異なり「親ディレクトリが未作成」を許す (新規フォルダ作成 + ファイル新規作成のため)。
+ * 多段検査: .md 拡張子 → root 配下 → docsWriteDirs 接頭辞 → isSecretPath → 実在祖先 realpath containment
+ *  → docsWriteDirs realpath 再確認 → 対象 symlink 拒否。
+ */
+export async function resolveDocWritePath(projectRoot, config, requestedRelPath) {
+    const root = path.resolve(projectRoot);
+    if (!requestedRelPath.endsWith('.md')) {
+        throw new PathValidationError('資料は .md ファイルのみ書き込めます');
+    }
+    const resolved = path.resolve(root, requestedRelPath);
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+        throw new PathValidationError('プロジェクトルート外への書込は許可されていません');
+    }
+    const writeDirs = effectiveDocsWriteDirs(root, config);
+    if (!writeDirs.some((dir) => isStrictlyInside(dir, resolved))) {
+        throw new PathValidationError('docsWriteDirs 外への書込は許可されていません');
+    }
+    if (isSecretPath(resolved)) {
+        throw new PathValidationError('秘匿ファイルへの書込は許可されていません');
+    }
+    // 親 (や中間 dir) が未作成なら「最も近い実在祖先」で containment を判定する (config-paths.ts と同方式)。
+    const rootReal = await fs.realpath(root).catch(() => root);
+    const { real: ancestorReal, missing } = await resolveNearestExistingAncestor(path.dirname(resolved));
+    if (ancestorReal !== rootReal && !ancestorReal.startsWith(rootReal + path.sep)) {
+        throw new PathValidationError('symlink 経由でプロジェクトルート外を指しています');
+    }
+    const parentReal = missing.length > 0 ? path.join(ancestorReal, ...missing) : ancestorReal;
+    // docsWriteDirs realpath 解決後も配下か再確認する
+    const allowedReals = await Promise.all(writeDirs.map((dir) => fs.realpath(dir).catch(() => dir)));
+    const stillInside = allowedReals.some((dir) => parentReal === dir || parentReal.startsWith(dir + path.sep));
+    if (!stillInside) {
+        throw new PathValidationError('symlink 経由で docsWriteDirs 外を指しています');
+    }
+    const canonical = path.join(parentReal, path.basename(resolved));
+    if (isSecretPath(canonical)) {
+        throw new PathValidationError('秘匿ファイルへの書込は許可されていません');
+    }
+    // 対象が既存 symlink なら拒否 (symlink 越しの書込防止)。未存在は ENOENT で素通り (新規作成)。
+    try {
+        const lst = await fs.lstat(canonical);
+        if (lst.isSymbolicLink()) {
+            throw new PathValidationError('symlink への書込は許可されていません');
+        }
+    }
+    catch (error) {
+        if (error instanceof PathValidationError)
+            throw error;
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    return { canonical, rootReal };
+}
+/**
+ * canonical の親ディレクトリを作成する (新規フォルダ込みの保存用)。
+ * resolveDocWritePath が親の realpath containment を済ませた canonical を渡す前提なので、
+ * ここでは未作成 segment を recursive mkdir するだけ (containment 再検査は呼び出し前提条件)。
+ */
+async function ensureDir(canonical) {
+    await fs.mkdir(path.dirname(canonical), { recursive: true });
+}
+export async function writeDoc(projectRoot, config, relPath, content, mode, baseMtimeMs) {
+    const { canonical, rootReal } = await resolveDocWritePath(projectRoot, config, relPath);
+    const writeDirs = effectiveDocsWriteDirs(path.resolve(projectRoot), config);
+    if (mode === 'overwrite') {
+        let serverContent = null;
+        let serverMtimeMs = null;
+        try {
+            serverContent = await readFileNoFollow(canonical);
+            serverMtimeMs = (await fs.lstat(canonical)).mtimeMs;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (serverMtimeMs === null) {
+            const err = new Error('資料が見つかりません');
+            err.code = 'ENOENT';
+            throw err;
+        }
+        if (serverMtimeMs !== null && serverMtimeMs !== baseMtimeMs) {
+            return { conflict: { serverContent: serverContent ?? '', serverMtimeMs } };
+        }
+        // 上書き前に旧版を .kanban/.trash へ退避する (ベストエフォート安全網・deleteDoc と同方式)。
+        try {
+            const kanbanDir = path.join(rootReal, '.kanban');
+            const kanbanReal = await resolveKanbanReal(path.resolve(projectRoot));
+            const stem = path.basename(canonical).replace(/\.md$/i, '');
+            const trashId = `doc-${stem.replace(/[^A-Za-z0-9._-]/g, '_')}`;
+            await snapshotToTrash(trashId, serverContent ?? '', kanbanDir, kanbanReal, config.trashKeep ?? DEFAULT_TRASH_KEEP);
+        }
+        catch {
+            // 退避できなくても上書きは進める (安全網のベストエフォート)
+        }
+        await safeWriteFile(canonical, content, writeDirs);
+    }
+    else {
+        await ensureDir(canonical);
+        await safeWriteFile(canonical, content, writeDirs, { exclusive: true });
+    }
+    const mtimeMs = (await fs.lstat(canonical)).mtimeMs;
+    return { path: path.relative(rootReal, canonical), mtimeMs };
+}
+/**
+ * docsWriteDirs 配下の資料を削除する。unlink の前に現内容を .kanban/.trash へコピー退避する (誤削除の安全網)。
+ * 退避はベストエフォート (失敗しても削除は進む)。対象不在は ENOENT を投げる (呼び出し側で 404)。
+ */
+export async function deleteDoc(projectRoot, config, relPath) {
+    const { canonical, rootReal } = await resolveDocWritePath(projectRoot, config, relPath);
+    // 現内容を読む (不在なら ENOENT → 呼び出し側 404)。symlink は resolveDocWritePath が既に拒否済み。
+    const content = await readFileNoFollow(canonical);
+    try {
+        const kanbanDir = path.join(rootReal, '.kanban');
+        const kanbanReal = await resolveKanbanReal(projectRoot);
+        const stem = path.basename(canonical).replace(/\.md$/i, '');
+        const trashId = `doc-${stem.replace(/[^A-Za-z0-9._-]/g, '_')}`;
+        await snapshotToTrash(trashId, content, kanbanDir, kanbanReal, config.trashKeep ?? DEFAULT_TRASH_KEEP);
+    }
+    catch {
+        // 退避できなくても削除は進める (安全網のベストエフォート)
+    }
+    await fs.rm(canonical, { force: false }); // 不在なら ENOENT (404)。symlink は事前拒否済み
+    return { path: path.relative(rootReal, canonical) };
+}
+/**
+ * docsWriteDirs 配下の .md ファイルツリーを構築する (buildDocsTree の write 版・保存先選択 UI 用)。
+ * buildDocsNode を共有し symlink 非追従・秘匿除外・空 dir 除外は同一。
+ */
+export async function buildDocsWriteTree(projectRoot, config) {
+    const root = path.resolve(projectRoot);
+    const trees = [];
+    for (const absDir of effectiveDocsWriteDirs(root, config)) {
+        const node = await buildDocsNode(root, absDir);
+        if (node && node.type === 'dir')
+            trees.push(node);
+    }
+    return trees;
+}