aizuchi 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,44 @@
 
 ## [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
 
 「今どうなっているか・次に何をすべきか」の見通しと、堅牢性・操作性を高めるリリース。

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 {

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;
+}

package/dist/server/lib/related-docs-validate.js

@@ -0,0 +1,37 @@
+import path from 'node:path';
+import { isSecretPath, isStrictlyInside, PathValidationError, sanitizeConfigDirEntries, } from './fs-safe.js';
+/**
+ * 資料からの起票 (波 VIII) で frontmatter に保存して良い related_docs パスかを検証する純ロジック。
+ *
+ * - 対象ディレクトリ = config.docsDirs ∪ config.docsWriteDirs を sanitizeConfigDirEntries で
+ *   root 配下に正規化し、.kanban 配下 / 秘匿パスを除外したもの (docs.ts の effectiveDocsDirs と同思想)。
+ * - 各要素は「.md 拡張子」「root 配下の相対パス (絶対 / .. を弾く)」「許可ディレクトリ配下」
+ *   「秘匿パスでない」を満たす必要がある。1 つでも違反すれば PathValidationError を投げる。
+ * - 同期判定のみ (fs.realpath は呼ばない): これは「読取」ではなく「frontmatter に書いて良い参照値か」の
+ *   妥当性チェック。symlink / TOCTOU 防御は読取時 (docs.ts resolveDocPath / readFileNoFollow) が担保する。
+ */
+export function assertRelatedDocsAllowed(projectRoot, config, docs) {
+    if (docs.length === 0)
+        return;
+    const root = path.resolve(projectRoot);
+    const kanbanDir = path.join(root, '.kanban');
+    const allowedDirs = sanitizeConfigDirEntries(root, [...config.docsDirs, ...config.docsWriteDirs]).filter((dir) => dir !== kanbanDir && !isStrictlyInside(kanbanDir, dir) && !isSecretPath(dir));
+    for (const rel of docs) {
+        if (!rel.endsWith('.md')) {
+            throw new PathValidationError('related_docs は .md ファイルのみ指定できます');
+        }
+        if (path.isAbsolute(rel)) {
+            throw new PathValidationError('related_docs に絶対パスは指定できません');
+        }
+        const resolved = path.resolve(root, rel);
+        if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+            throw new PathValidationError('related_docs にプロジェクトルート外のパスは指定できません');
+        }
+        if (isSecretPath(resolved)) {
+            throw new PathValidationError('related_docs に秘匿ファイルは指定できません');
+        }
+        if (!allowedDirs.some((dir) => isStrictlyInside(dir, resolved))) {
+            throw new PathValidationError('related_docs は docsDirs / docsWriteDirs 配下の資料のみ指定できます');
+        }
+    }
+}

package/dist/server/lib/task-ops.js

@@ -100,6 +100,7 @@ export class TaskOps {
                     created_by: parsed.data.created_by,
                     priority: parsed.data.priority ?? 'medium',
                     labels: parsed.data.labels ?? [],
+                    related_docs: parsed.data.related_docs,
                     blocked_type: null,
                     blocked_reason: null,
                     created: now,

package/dist/shared/ai-health.js

@@ -0,0 +1,78 @@
+/**
+ * AI オンボーディング診断 (TASK-023)。
+ * board の warnings を AI メンバー別に集計し、各 warning kind に「直し方」の説明を付けた
+ * 構造を返す純関数。新データ源・新依存・永続化なし。
+ *
+ * now は引数注入 (Date.now ハードコード禁止・テスト再現性)。
+ */
+/**
+ * warnings を AI メンバー別・kind 別に group-by する。
+ *
+ * - warning が特定の AI メンバーに紐付くか判定: taskId が null でない場合はタスクのパスから
+ *   直接判定できないため、メンバー ID を message 内から照合する (unregistered_member / mode_violation)。
+ *   それ以外の kind (invalid_task / duplicate_id / invalid_config) は AI に特定紐付けできないため
+ *   全 AI メンバーに共通の「設定上の問題」として集約する。
+ * - assignee / created_by 別の精細な帰属は taskView へのアクセスが必要で pure fn では難しいため、
+ *   警告の message 文字列に含まれる member id を照合する簡易戦略を取る。
+ *
+ * @param warnings  board.warnings (GET /api/board の warnings)
+ * @param members   config.members (全メンバー)
+ */
+export function deriveAiHealth(warnings, members) {
+    const aiMembers = members.filter((m) => m.type === 'ai');
+    if (aiMembers.length === 0) {
+        return { members: [], noAiMembers: true };
+    }
+    const results = aiMembers.map((member) => {
+        // このメンバーに紐付く warning を収集する
+        const memberWarnings = warnings.filter((w) => isWarningForMember(w, member.id));
+        // kind 別にグループ化する
+        const kindMap = new Map();
+        for (const w of memberWarnings) {
+            const existing = kindMap.get(w.kind);
+            if (existing) {
+                existing.push(w);
+            }
+            else {
+                kindMap.set(w.kind, [w]);
+            }
+        }
+        const groups = Array.from(kindMap.entries()).map(([kind, ws]) => ({
+            kind,
+            warnings: ws,
+        }));
+        return {
+            member,
+            groups,
+            totalWarnings: memberWarnings.length,
+        };
+    });
+    return { members: results, noAiMembers: false };
+}
+/**
+ * warning が特定のメンバー ID に関係するか判定する。
+ *
+ * 帰属ルール:
+ * - `mode_violation`: message に memberId が含まれる (board.ts が `AI (${created_by})` と書く)
+ * - `unregistered_member`: message に `"${memberId}"` が含まれる (board.ts が `created_by "${id}"` / `assignee "${id}"` と書く)
+ * - `invalid_task` / `duplicate_id`: タスク起票者を message から特定できないが、メンバーが 1 人なら
+ *   そのメンバーに帰属させる。複数の AI メンバーがいる場合は全員に共通の問題として扱う (= 全員に紐付ける)
+ * - `invalid_config`: config 全体の問題なので全 AI メンバーに共通 (= 全員に紐付ける)
+ */
+function isWarningForMember(warning, memberId) {
+    switch (warning.kind) {
+        case 'mode_violation':
+            // board.ts: `AI (${frontmatter.created_by}) が ...`
+            return warning.message.includes(`(${memberId})`);
+        case 'unregistered_member':
+            // board.ts: `created_by "${id}" は config.members に未登録` / `assignee "${id}" ...`
+            return warning.message.includes(`"${memberId}"`);
+        case 'invalid_task':
+        case 'duplicate_id':
+        case 'invalid_config':
+            // task/config 全体の問題。AI メンバー全員に共通の診断事項として表示する
+            return true;
+        default:
+            return false;
+    }
+}

package/dist/shared/schema.js

@@ -15,6 +15,11 @@ export const UI_LANGS = ['en', 'ja'];
 export const DEFAULT_PORT = 5151;
 /** overview モードの既定ポート (波 VII)。serve の 5151 と衝突しない値・1 箇所集約 */
 export const DEFAULT_OVERVIEW_PORT = 5152;
+/**
+ * serve のポート自動フォールバック試行回数。起点 (--port 明示時を除く) が使用中なら
+ * 起点〜起点+この数-1 まで順に空きを探す。複数プロジェクトの同時 serve 用 (例: 5151〜5170)。
+ */
+export const PORT_FALLBACK_ATTEMPTS = 20;
 // 日付は文字列のまま扱い、Date 化しない (js-yaml JSON_SCHEMA エンジンと対になる規則)。
 // zod の datetime({ offset: true }) を使い、月 13 / 時 25 のような実在しない日時を弾く
 // (自前正規表現は桁数だけ見て実在性を見ず、経過時間表示が NaN になりうる — PM Round 1 Minor #8)。
@@ -145,6 +150,9 @@ export const configSchema = z.object({
     views: z.array(z.object({ id: z.string().min(1), hidden: z.boolean().optional() })).default([]),
     // 関連資料ディレクトリ (波 VIII)。プロジェクトルートからの相対パス。既定は空 = 機能オフ (UI 非表示)
     docsDirs: z.array(z.string().min(1)).default([]),
+    // 資料の書込先ディレクトリ (資料エディタ MVP)。読取 (docsDirs) と分離し、既定は空 = 書込オフ。
+    // 書込 API (POST/PUT/DELETE /api/docs) はこの配下のみ許可する (root 配下相対)。
+    docsWriteDirs: z.array(z.string().min(1)).default([]),
     // ごみ箱 (.kanban/.trash) の同 id あたり退避世代の保持件数。任意・後方互換 (未設定は DEFAULT_TRASH_KEEP)。
     // 破壊的書込の直前に旧版を .trash へコピー退避し、この件数を超えた古い世代を刈り取る (誤上書きの安全網)
     trashKeep: z.number().int().positive().optional(),
@@ -275,6 +283,9 @@ export const newTaskInputSchema = z
     labels: z.array(z.string().min(1)).optional(),
     // 本文 (波 VI: テンプレートからのプリフィル用)。省略時はサーバーが既定本文テンプレートを使う
     body: z.string().optional(),
+    // 波 VIII: 関連資料 (プロジェクトルートからの相対パス配列)。任意・後方互換。
+    // 範囲 (docsDirs / docsWriteDirs 配下か) はサーバー側 assertRelatedDocsAllowed が検証する
+    related_docs: z.array(z.string().min(1)).optional(),
 })
     .strict();
 /**