aizuchi 0.1.0

package/dist/server/lib/git.js

@@ -0,0 +1,100 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+/**
+ * git 履歴連携 (S-1・read-only)。コミットメッセージの `TASK-xxx` をパースし、タスクに紐づくコミットを返す。
+ *
+ * セキュリティ設計 (中核):
+ * - **`execFile('git', [args], {cwd})` を使う。シェルを経由しない** (`exec` / `shell:true` 禁止 =
+ *   インジェクション面ゼロ)。引数は固定配列で、ユーザー由来の値 (タスク ID) は引数として渡すが、
+ *   その前に厳格バリデーション (TASK_ID_RE) を通す。不一致なら git を起動せず [] を返す。
+ * - `--` 区切りでオプション終端を明示。固定フォーマット `--format=%H%x00%s%x00%aI` (NUL 区切りで解析安全)。
+ * - read-only サブコマンドのみ (`git log --all --grep` / `git rev-parse`)。
+ * - N-1 (外部通信なし): git はローカル subprocess のみ。fetch / pull は実行しない (log は外部に出ない)。
+ * - graceful degradation: 非 git リポ / git 未インストール (ENOENT) / タイムアウトは静かに無効化して [] を返す。
+ * - N-8: エラー時に cwd やフルパスをレスポンス / ログに出さない (catch して [] に倒す)。
+ */
+const execFileAsync = promisify(execFile);
+/** git の実行タイムアウト (巨大リポでの暴走防止) */
+const GIT_TIMEOUT_MS = 3000;
+/** 検索するコミットの上限 (詳細パネル表示用。過大なリポでの応答肥大を防ぐ) */
+const MAX_COMMITS = 50;
+/** NUL (U+0000) 区切り文字。LEARN#13: invisible 制御文字は literal ではなく \uXXXX escape で書く */
+const NUL = '\u0000';
+/**
+ * タスク ID の許可形式 (config.idPrefix + 数字)。`^[A-Za-z0-9_]+-\d+$` のみ許可する。
+ * 仕様の `^[A-Za-z0-9]+-\d+$` に config.idPrefix が許す `_` を加えた字種 (idPrefix は `^[A-Za-z0-9_]+$`)。
+ * いずれもシェルメタ文字を含まないため execFile の引数として安全 (二重防御)。
+ * これにマッチしない値 (`; rm -rf` 等のインジェクション文字列を含む) は git を起動せず [] を返す。
+ * execFile はそもそも引数をシェル解釈しないが、`--grep` の値として渡る前に二重で安全側に倒す。
+ */
+const TASK_ID_RE = /^[A-Za-z0-9_]+-\d+$/;
+export function isValidTaskId(id) {
+    return TASK_ID_RE.test(id);
+}
+/**
+ * 指定ディレクトリが git の作業ツリー内かを判定する (read-only)。
+ * 非 git / git 未インストール (ENOENT) / タイムアウトは false (機能を静かに無効化する)。
+ */
+async function isGitRepo(cwd) {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', '--is-inside-work-tree'], {
+            cwd,
+            timeout: GIT_TIMEOUT_MS,
+        });
+        return stdout.trim() === 'true';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * タスク ID を含むコミットを検索して返す (read-only)。
+ * - ID が TASK_ID_RE に不一致なら git を起動せず [] (インジェクション防御)。
+ * - 非 git / git 未インストール / タイムアウト / 該当なしは [] (graceful degradation)。
+ * - subject に ID 文字列が部分一致するコミットを新しい順に最大 MAX_COMMITS 件返す。
+ */
+export async function findCommitsForTask(cwd, taskId) {
+    if (!isValidTaskId(taskId))
+        return [];
+    if (!(await isGitRepo(cwd)))
+        return [];
+    try {
+        const { stdout } = await execFileAsync('git', [
+            'log',
+            '--all',
+            `--max-count=${MAX_COMMITS}`,
+            // NUL 区切りの固定フォーマット: hash NUL subject NUL authorDate(ISO)。レコード間は改行
+            '--format=%H%x00%s%x00%aI',
+            // taskId を --grep の値として渡す。--fixed-strings で正規表現メタ文字をリテラル扱いにする
+            // (TASK_ID_RE 通過後なのでメタ文字は入らないが二重防御)。大文字小文字は区別する。
+            '--fixed-strings',
+            `--grep=${taskId}`,
+            // `--` でオプション終端を明示 (以降に pathspec が来ないことを示し、ID が誤ってパスとして解釈されない)
+            '--',
+        ], { cwd, timeout: GIT_TIMEOUT_MS, maxBuffer: 1024 * 1024 });
+        return parseCommitLog(stdout);
+    }
+    catch {
+        // git の異常終了 (壊れたリポ等) / タイムアウトは静かに [] (N-8: 詳細を露出しない)
+        return [];
+    }
+}
+/**
+ * `git log --format=%H%x00%s%x00%aI` の出力を CommitRef[] に解析する。
+ * 各レコードは改行区切り、フィールドは NUL (U+0000) 区切り。hash / authorDate が空の行はスキップする。
+ */
+export function parseCommitLog(stdout) {
+    const commits = [];
+    for (const line of stdout.split('\n')) {
+        if (line === '')
+            continue;
+        const parts = line.split(NUL);
+        if (parts.length < 3)
+            continue;
+        const [hash, subject, authorDate] = parts;
+        if (hash === '' || authorDate === '')
+            continue;
+        commits.push({ hash, subject, authorDate });
+    }
+    return commits;
+}

package/dist/server/lib/id.js

@@ -0,0 +1,54 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { collectKanbanFilesNoSymlink } from './fs-safe.js';
+/**
+ * ID 採番 (要件 §5.5): `tasks/` と `archive/**` を走査し、`<idPrefix>-<番号>.md` の
+ * 最大番号 + 1 をゼロ詰め 3 桁で返す (桁あふれ時は自然に 4 桁以上になる)。
+ * ID = ファイル名のため、frontmatter ではなくファイル名を走査する。
+ *
+ * R17-F (M1): 走査を realpath containment 化する。旧 `fs.readdir({recursive:true})` は中間 dir symlink
+ * (`.kanban/tasks/sub → 外部dir`) を辿り、外部 dir の `<prefix>-99999.md` 等で採番番号を汚染できた
+ * (内容漏洩なし・exclusive create で一意性は保持・弱い DoS)。collectKanbanFilesNoSymlink で
+ * symlink 非追従 + 信頼境界内に限定して走査する (FIX-D と同型・LEARN#6 boundary drift 完結)。
+ * 信頼境界は kanbanDir 自身の realpath (呼出側が `<projectRoot>/.kanban` を渡す既知のディレクトリ)。
+ */
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+export async function allocateNextId(kanbanDir, idPrefix) {
+    const pattern = new RegExp(`^${escapeRegExp(idPrefix)}-(\\d+)\\.md$`);
+    let max = 0;
+    // kanbanDir 自身の realpath を信頼境界にする (kanbanDir が symlink でも実体内に正規化)。
+    // kanbanDir 不在なら走査対象ゼロ → 初番に倒す
+    let kanbanReal;
+    try {
+        kanbanReal = await fs.realpath(kanbanDir);
+    }
+    catch {
+        return `${idPrefix}-${String(max + 1).padStart(3, '0')}`;
+    }
+    for (const sub of ['tasks', 'archive']) {
+        const dir = path.join(kanbanReal, sub);
+        // collectKanbanFilesNoSymlink は不在 dir / symlink dir / 中間 dir symlink を [] (skip) に倒すため try/catch 不要
+        const files = await collectKanbanFilesNoSymlink(dir, kanbanReal, (abs) => pattern.test(path.basename(abs)));
+        for (const abs of files) {
+            const matched = path.basename(abs).match(pattern);
+            if (matched)
+                max = Math.max(max, Number.parseInt(matched[1], 10));
+        }
+    }
+    return `${idPrefix}-${String(max + 1).padStart(3, '0')}`;
+}
+/**
+ * プロセス内 Promise キュー。
+ * POST /api/tasks の「走査 → 採番 → 書込」を直列化し、同時起票の ID 重複を防ぐ。
+ * 前のジョブが失敗しても後続は実行する。
+ */
+export function createSerialQueue() {
+    let tail = Promise.resolve();
+    return function enqueue(job) {
+        const next = tail.then(job, job);
+        tail = next.then(() => undefined, () => undefined);
+        return next;
+    };
+}

package/dist/server/lib/pinpoint.js

@@ -0,0 +1,225 @@
+import yaml from 'js-yaml';
+/** 値を 1 行の YAML スカラーとして出力する (serializeTaskFile と同じ JSON_SCHEMA 規則) */
+function dumpScalar(value) {
+    if (typeof value === 'string' && /[\r\n]/.test(value)) {
+        // 改行入り文字列は YAML 互換の JSON 文字列にして 1 行に収める (行置換モデルを守る)
+        return JSON.stringify(value);
+    }
+    return yaml.dump(value, { schema: yaml.JSON_SCHEMA, lineWidth: -1 }).replace(/\n$/, '');
+}
+/** 行置換を適用した新しいファイル全文を返す。frontmatter が無いファイルは例外 */
+export function applyPinpointPatch(raw, patch) {
+    // 先頭 BOM は保全しつつ、判定・置換は BOM を除いたテキストで行う (parseTaskFile と挙動を揃える)
+    const bom = raw.startsWith('\uFEFF') ? '\uFEFF' : '';
+    const text = bom ? raw.slice(1) : raw;
+    const lines = text.split('\n');
+    if ((lines[0] ?? '').replace(/\r$/, '') !== '---') {
+        throw new Error('frontmatter ブロックが見つからない (ファイル先頭が --- ではない)');
+    }
+    let closeIndex = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if ((lines[i] ?? '').replace(/\r$/, '') === '---') {
+            closeIndex = i;
+            break;
+        }
+    }
+    if (closeIndex === -1) {
+        throw new Error('frontmatter の閉じ --- が見つからない');
+    }
+    const replaceLine = (key, value) => {
+        const rendered = `${key}: ${dumpScalar(value)}`;
+        for (let i = 1; i < closeIndex; i++) {
+            const line = (lines[i] ?? '').replace(/\r$/, '');
+            // トップレベルのキー行のみ一致する (ブロックスカラー内の行はインデントされるため一致しない)
+            if (line === `${key}:` || line.startsWith(`${key}: `) || line.startsWith(`${key}:\t`)) {
+                lines[i] = (lines[i] ?? '').endsWith('\r') ? `${rendered}\r` : rendered;
+                return;
+            }
+        }
+        // 行が無い場合 (AI が省略可能フィールドを書かずに起票した等) は閉じ --- の直前に追記する。
+        // EOL は閉じ --- 行に合わせる (CRLF ファイルに LF 行を混在させない)
+        const closeHasCr = (lines[closeIndex] ?? '').endsWith('\r');
+        lines.splice(closeIndex, 0, closeHasCr ? `${rendered}\r` : rendered);
+        closeIndex += 1;
+    };
+    replaceLine('status', patch.status);
+    replaceLine('updated', patch.updated);
+    if ('blocked_type' in patch)
+        replaceLine('blocked_type', patch.blocked_type ?? null);
+    if ('blocked_reason' in patch)
+        replaceLine('blocked_reason', patch.blocked_reason ?? null);
+    return bom + lines.join('\n');
+}
+/** frontmatter ブロック (先頭 --- 〜 次の ---) の行範囲を返す。無ければ null。BOM 込みで扱う */
+function frontmatterRange(text) {
+    const lines = text.split('\n');
+    if ((lines[0] ?? '').replace(/\r$/, '') !== '---')
+        return null;
+    for (let i = 1; i < lines.length; i++) {
+        if ((lines[i] ?? '').replace(/\r$/, '') === '---')
+            return { lines, close: i };
+    }
+    return null;
+}
+/** タスク ID トークンの正規表現を組み立てる (単語境界。depends_on の flow / 通常表記の両方に効く) */
+function idTokenRe(id) {
+    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(?<![A-Za-z0-9_-])${escaped}(?![A-Za-z0-9_-])`, 'g');
+}
+/**
+ * 重複 ID リネーム支援 (F-6-5)。frontmatter の `id:` 行を newId に置き換える (本文は保全)。
+ * frontmatter が無い / id 行が無い場合は元の raw をそのまま返す (防御)。
+ */
+export function renameTaskId(raw, newId) {
+    const bom = raw.startsWith('') ? '' : '';
+    const text = bom ? raw.slice(1) : raw;
+    const fm = frontmatterRange(text);
+    if (!fm)
+        return raw;
+    const { lines, close } = fm;
+    for (let i = 1; i < close; i++) {
+        const line = (lines[i] ?? '').replace(/\r$/, '');
+        if (line === 'id:' || line.startsWith('id: ') || line.startsWith('id:\t')) {
+            const rendered = `id: ${newId}`;
+            lines[i] = (lines[i] ?? '').endsWith('\r') ? `${rendered}\r` : rendered;
+            break;
+        }
+    }
+    return bom + lines.join('\n');
+}
+/**
+ * 他タスクの frontmatter `depends_on` の oldId を newId に置き換える (F-6-5 の連鎖更新)。
+ * flow 形式 (`depends_on: [TASK-001]`) と block 形式 (`depends_on:` 改行 `  - TASK-001`) の
+ * 両方に対応する (R8-3)。本文中の同名トークンや他フィールドには触れない。
+ * depends_on に oldId が含まれなければ raw をそのまま返す (変更なし)。
+ */
+export function replaceDependsOnId(raw, oldId, newId) {
+    const bom = raw.startsWith('') ? '' : '';
+    const text = bom ? raw.slice(1) : raw;
+    const fm = frontmatterRange(text);
+    if (!fm)
+        return raw;
+    const { lines, close } = fm;
+    const tokenRe = idTokenRe(oldId);
+    let changed = false;
+    const replaceInLine = (i) => {
+        const cr = (lines[i] ?? '').endsWith('\r');
+        const line = (lines[i] ?? '').replace(/\r$/, '');
+        const replaced = line.replace(tokenRe, newId);
+        if (replaced !== line) {
+            lines[i] = cr ? `${replaced}\r` : replaced;
+            changed = true;
+        }
+    };
+    for (let i = 1; i < close; i++) {
+        const line = (lines[i] ?? '').replace(/\r$/, '');
+        if (line !== 'depends_on:' && !line.startsWith('depends_on: ') && !line.startsWith('depends_on:\t'))
+            continue;
+        // flow 形式 (inline 値) の置換
+        replaceInLine(i);
+        // block 形式: depends_on: の後に inline 値が無い (改行のみ) 場合、続くインデント行 (`  - ...`) を走査
+        const inlineValue = line.replace(/^depends_on:\s*/, '');
+        if (inlineValue === '') {
+            for (let j = i + 1; j < close; j++) {
+                const item = (lines[j] ?? '').replace(/\r$/, '');
+                // インデントされた list 項目 (`- ...`) のみ block の続き。非インデント = ブロック終了
+                if (/^\s+-\s/.test(item)) {
+                    replaceInLine(j);
+                }
+                else if (item.trim() === '') {
+                    continue; // 空行はスキップして続ける
+                }
+                else {
+                    break; // 次のトップレベルキー = depends_on ブロック終了
+                }
+            }
+        }
+    }
+    return changed ? bom + lines.join('\n') : raw;
+}
+/**
+ * verify-after-patch ガード (PM Round 1 #2/#3/#6 への包括対処)。
+ *
+ * `applyPinpointPatch` の行置換は「parse が受理する YAML 表記」の部分集合しか正しく扱えない
+ * (block scalar / コロン前スペース / quoted key / インデント継続行 等)。これらでは
+ * 「parse は通るのに行置換が値を壊す or 取りこぼす」非対称が起きうる。
+ *
+ * そこで patch 前後を再 parse して比較し、
+ * 「patch が触れるべき frontmatter フィールドだけが・意図どおりの値に変わり、本文 (body) は不変」
+ * であることを検証する。不一致なら理由文字列を返す (呼び出し側で書込を拒否する)。問題なければ null。
+ *
+ * 本文比較 (PM Round 2 R2-2): 現状の applyPinpointPatch は frontmatter 行しか触らないため body は
+ * 不変のはずだが、将来パッチ対象が増えたときの body silent 破壊をこのガードで止める。
+ *
+ * @param before patch 前の parse 結果 (parseTaskFile(raw))
+ * @param after  patch 後の parse 結果 (parseTaskFile(patched))
+ */
+export function verifyPinpointResult(before, after, patch) {
+    const beforeData = before.data;
+    const afterData = after.data;
+    // patch が意図する各フィールドの最終値 (blocked_* は patch に無ければ変更しない)
+    const intended = {
+        status: patch.status,
+        updated: patch.updated,
+    };
+    if ('blocked_type' in patch)
+        intended.blocked_type = patch.blocked_type ?? null;
+    if ('blocked_reason' in patch)
+        intended.blocked_reason = patch.blocked_reason ?? null;
+    const intendedKeys = new Set(Object.keys(intended));
+    // patch 対象フィールドが意図どおりの値になっているか
+    for (const [key, value] of Object.entries(intended)) {
+        if (!valuesEqual(afterData[key], value)) {
+            return `行置換が ${key} を正しく書き換えられなかった (この表記はピンポイント書換に未対応)`;
+        }
+    }
+    // patch 対象外のフィールドが変わっていないか (block scalar の孤児化等で巻き添えが出ないか)。
+    // 両者のキー集合の和を走査し、patch 対象外で差分があれば拒否する
+    const allKeys = new Set([...Object.keys(beforeData), ...Object.keys(afterData)]);
+    for (const key of allKeys) {
+        if (intendedKeys.has(key))
+            continue;
+        if (!valuesEqual(beforeData[key], afterData[key])) {
+            return `行置換が意図しないフィールド ${key} を変更した (この表記はピンポイント書換に未対応)`;
+        }
+    }
+    // 本文 (body) は frontmatter の行置換で変わってはならない (R2-2)
+    if (before.body !== after.body) {
+        return '行置換が本文を変更した (この表記はピンポイント書換に未対応)';
+    }
+    return null;
+}
+/** JSON 直列化で値の等価判定をする (frontmatter の値はスカラー / 配列 / null のみ) */
+function valuesEqual(a, b) {
+    if (a === b)
+        return true;
+    return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+/**
+ * verify-after-rename ガード (R8-4)。renameTaskId の結果を再 parse して検証する。
+ * 「新 id が newId (= ファイル名) と一致 & id 以外の frontmatter フィールドと body は不変」を確認。
+ * drift があれば理由文字列を返す (呼び出し側で書込を拒否し元ファイルを残す)。問題なければ null。
+ *
+ * @param before rename 前の parse 結果 (parseTaskFile(raw))
+ * @param after  rename 後の parse 結果 (parseTaskFile(renamed))
+ * @param newId  期待する新 ID (= 新ファイル名の basename)
+ */
+export function verifyRename(before, after, newId) {
+    // id が確実に newId へ変わったか (= ファイル名と frontmatter id の整合)
+    if (after.data.id !== newId) {
+        return `id が ${newId} に書き換わっていない (この id 表記はリネームに未対応)`;
+    }
+    // id 以外の全フィールドは不変であること (壊れた id 表記で他フィールドを巻き添えにしていないか)
+    const allKeys = new Set([...Object.keys(before.data), ...Object.keys(after.data)]);
+    for (const key of allKeys) {
+        if (key === 'id')
+            continue;
+        if (!valuesEqual(before.data[key], after.data[key])) {
+            return `リネームが意図しないフィールド ${key} を変更した`;
+        }
+    }
+    if (before.body !== after.body) {
+        return 'リネームが本文を変更した';
+    }
+    return null;
+}

package/dist/server/lib/proposal.js

@@ -0,0 +1,93 @@
+/**
+ * 提案ワークフロー (F-3) の本文操作。却下時に作業ログへ理由を追記する純関数。
+ */
+// 作業ログ見出し: 日本語テンプレ (`## 作業ログ`) と英語 (`## Work log`) の両方を許容する
+const WORK_LOG_HEADING_RE = /^#{1,6}\s*(?:作業ログ|work log)\s*$/i;
+// 承認痕跡: approve API が作業ログに残す `[approve]` タグ行 (F-3-4 誤検知防止 R6-1)
+const APPROVE_TRACE_RE = /^\s*-\s*\S.*\[approve\]/m;
+/**
+ * 作業ログに承認痕跡 (`[approve]` を含むログ行) があるかを判定する。
+ * proposed→approve した正規タスクと、AI が proposed を経ず直接 todo 起票した違反を区別するために使う。
+ */
+export function hasApprovalTrace(body) {
+    return APPROVE_TRACE_RE.test(body);
+}
+/**
+ * frontmatter ブロック (先頭 `---` 〜 2 つ目の `---` の行) を header として保持したまま、
+ * 本文 (body) だけを新しい内容に差し替えた raw 全文を返す。
+ * frontmatter が無ければ全体を body 扱いにして newBody を返す。
+ * BOM・CRLF は header 側でそのまま保全される (行置換しないため frontmatter はバイト不変)。
+ */
+export function replaceBody(raw, newBody) {
+    const bom = raw.startsWith('') ? '' : '';
+    const text = bom ? raw.slice(1) : raw;
+    const lines = text.split('\n');
+    if ((lines[0] ?? '').replace(/\r$/, '') !== '---') {
+        // frontmatter 無し: 全体が本文
+        return newBody;
+    }
+    let closeIndex = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if ((lines[i] ?? '').replace(/\r$/, '') === '---') {
+            closeIndex = i;
+            break;
+        }
+    }
+    if (closeIndex === -1) {
+        return newBody; // 閉じ --- が無い壊れたファイル: 防御的に body 扱い
+    }
+    // header = 先頭 〜 閉じ --- 行 (その行の EOL は含む)。本文はその直後から
+    const header = lines.slice(0, closeIndex + 1).join('\n');
+    // 元 raw の「閉じ --- 行の直後の改行」を保つため、header の後に \n + newBody を置く。
+    // gray-matter の content は閉じ --- 直後の 1 改行を取り除いた形なので、ここで 1 つ補う
+    return `${bom}${header}\n${newBody}`;
+}
+/**
+ * タスク本文の `## 作業ログ` セクション末尾に 1 行追記する。
+ * - セクションがあれば、その内容ブロックの末尾 (次見出し or EOF 直前) に挿入
+ * - セクションが無ければ、本文末尾に `## 作業ログ` 見出しごと追加
+ * 改行入りの line は受け付けない (呼び出し側で 1 行に正規化する前提)。
+ * EOL は本文の既存スタイル (CRLF / LF) に合わせる (R6 Minor: CRLF ファイルに LF 行を混在させない)。
+ */
+export function appendWorkLogLine(body, line) {
+    return appendUnderHeading(body, WORK_LOG_HEADING_RE, '## 作業ログ', line);
+}
+// やりとり (タスクコメント) 見出し: 日本語 (`## やりとり`) と英語 (`## Comments` / `## Discussion`) を許容
+const COMMENT_HEADING_RE = /^#{1,6}\s*(?:やりとり|comments?|discussion)\s*$/i;
+/**
+ * タスクコメント (往復) を本文の `## やりとり` セクション末尾に 1 行追記する。
+ * 作業ログと同形式 (`- 時刻 [member] msg`)。セクションが無ければ見出しごと追加する。
+ */
+export function appendCommentLine(body, line) {
+    return appendUnderHeading(body, COMMENT_HEADING_RE, '## やりとり', line);
+}
+/**
+ * 指定見出しのセクション末尾に `- <line>` を追記する共通処理 (作業ログ / やりとり で共用)。
+ * - セクションがあればその内容ブロック末尾 (次見出し or EOF 直前) に挿入
+ * - 無ければ本文末尾に見出しごと追加
+ * EOL は本文の既存スタイル (CRLF / LF) に合わせる (R6 Minor: 混在させない)。
+ */
+function appendUnderHeading(body, headingRe, defaultHeading, line) {
+    const eol = body.includes('\r\n') ? '\r\n' : '\n';
+    const entry = `- ${line}`;
+    const lines = body.split(eol);
+    const headingIndex = lines.findIndex((l) => headingRe.test(l.trim()));
+    if (headingIndex === -1) {
+        const trimmed = body.replace(/(\r?\n)+$/, '');
+        const prefix = trimmed.length > 0 ? `${trimmed}${eol}${eol}` : '';
+        return `${prefix}${defaultHeading}${eol}${entry}${eol}`;
+    }
+    let insertAt = lines.length;
+    for (let i = headingIndex + 1; i < lines.length; i++) {
+        if (/^#{1,6}\s/.test(lines[i])) {
+            insertAt = i;
+            break;
+        }
+    }
+    let pos = insertAt;
+    while (pos > headingIndex + 1 && lines[pos - 1].trim() === '') {
+        pos -= 1;
+    }
+    lines.splice(pos, 0, entry);
+    return lines.join(eol);
+}

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

@@ -0,0 +1,132 @@
+import matter from 'gray-matter';
+import yaml from 'js-yaml';
+/**
+ * タスクファイル (Markdown + YAML frontmatter) の parse / serialize。
+ *
+ * - parse: gray-matter に js-yaml の JSON_SCHEMA エンジンを注入し、
+ *   `created: 2026-06-10T10:00:00+09:00` のような日付を Date 化せず文字列のまま扱う
+ *   (既定エンジンは YAML 1.1 timestamp として Date 化し、再出力で UTC に書き換わるため)。
+ * - serialize: 新規作成専用。既存ファイルの更新は pinpoint.ts の行置換を使い、
+ *   parse → stringify の再シリアライズは行わない (クォート・空白の正規化で git diff が壊れるため)。
+ */
+/**
+ * YAML 構文エラー。js-yaml の YAMLException と違い、message にファイル内容の抜粋を
+ * 含まない (N-8: タスク本文・設定内容をサーバーログへ出さない契約のため、ログ出力可)。
+ *
+ * js-yaml の reason は基本的に固定の英語テンプレートだが、一部のエラー
+ * (`unidentified alias "<名前>"` / `unknown tag !<...>`) はファイル由来の識別子を
+ * 引用・山括弧で埋め込む。これらは sanitizeYamlReason で伏字化してから持たせる。
+ */
+export class TaskFileParseError extends Error {
+    line;
+    column;
+    constructor(message, line, column) {
+        super(message);
+        this.name = 'TaskFileParseError';
+        this.line = line;
+        this.column = column;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * js-yaml の reason からファイル由来の文字列を伏字化する (N-8)。
+ *
+ * js-yaml@4 がファイル内容を reason に埋め込むテンプレートは 3 系統:
+ * 1. 引用符の中: `unidentified alias "SECRET"` / `undeclared tag handle "!x!"`
+ * 2. 山括弧の中: `unknown tag !<tag:...:python/secret>`
+ * 3. **区切りなし**で `": "` (コロン + 空白) の直後にベタ書き:
+ *    `tag name cannot contain such characters: <生内容>` (loader.js:1316) /
+ *    `tag name is malformed: <生内容>` (loader.js:1322) /
+ *    `tag prefix is malformed: <生内容>` (loader.js:346)
+ *
+ * 1/2 は中身だけ伏字化し、3 は `": "` 以降を丸ごと固定文言に倒す。
+ * js-yaml の安全な reason は top-level に `": "` を持たないため過剰伏字にならない
+ * (実測確認済み)。将来 js-yaml が `prefix: content` 形の新テンプレートを足しても
+ * この `": "` ルールで素通しを防げる。
+ *
+ * R14-2 (N-8): 最終ルールの `.*` は改行非マッチのため、複数行 verbatim tag を含む reason で
+ * 改行後のタスク本文が伏字化されずエラー / レスポンスに残る漏洩があった。`[\s\S]` で改行込み全消去にする。
+ */
+export function sanitizeYamlReason(reason) {
+    return reason
+        .replace(/"[^"]*"/g, '"***"')
+        .replace(/'[^']*'/g, "'***'")
+        .replace(/<[^>]*>/g, '<***>')
+        .replace(/: [\s\S]*$/, ': ***');
+}
+const yamlEngine = {
+    parse(input) {
+        let loaded;
+        try {
+            loaded = yaml.load(input, { schema: yaml.JSON_SCHEMA });
+        }
+        catch (error) {
+            // YAMLException.message はエラー位置周辺のファイル内容を複数行含むため、
+            // 位置情報だけを持つ専用エラーに変換する (N-8)。reason に紛れたファイル由来の
+            // 識別子 (alias / tag 名) も sanitizeYamlReason で伏字化する
+            const mark = error.mark;
+            const rawReason = error.reason ?? '不明な構文エラー';
+            const reason = sanitizeYamlReason(rawReason);
+            const line = typeof mark?.line === 'number' ? mark.line + 1 : null;
+            const column = typeof mark?.column === 'number' ? mark.column + 1 : null;
+            const position = line !== null ? ` (${line} 行目${column !== null ? ` ${column} 文字目` : ''})` : '';
+            throw new TaskFileParseError(`YAML 構文エラー: ${reason}${position}`, line, column);
+        }
+        // スカラーや配列だけの frontmatter は不正なので空に正規化する (zod の必須欠落として検出される)
+        return isPlainObject(loaded) ? loaded : {};
+    },
+    stringify() {
+        throw new Error('既存タスクの再シリアライズは禁止。新規作成は serializeTaskFile() を使う');
+    },
+};
+/**
+ * タスクファイルの生テキストを frontmatter と本文に分解する。
+ * YAML 構文エラー時は TaskFileParseError を投げる (呼び出し側で警告に変換する)。
+ * 先頭の UTF-8 BOM は除いて扱う (gray-matter 内部の BOM 除去と判定を揃える)。
+ */
+export function parseTaskFile(raw) {
+    const text = raw.startsWith('\uFEFF') ? raw.slice(1) : raw;
+    const file = matter(text, { engines: { yaml: yamlEngine } });
+    return {
+        data: file.data,
+        body: file.content,
+        // gray-matter \u306F\u958B\u304D `---` \u306E\u884C\u672B\u306B\u7A7A\u767D / \u30BF\u30D6\u304C\u4ED8\u3044\u3066\u3082 frontmatter \u3068\u3057\u3066\u53D7\u7406\u3059\u308B\u3002
+        // \u5224\u5B9A\u3092\u305D\u308C\u306B\u5408\u308F\u305B\u300C\u30DC\u30FC\u30C9\u306B\u306F\u51FA\u308B\u306E\u306B hasFrontmatter=false\u300D\u306E\u975E\u5BFE\u79F0\u3092\u9632\u3050
+        hasFrontmatter: /^---[ \t]*\r?\n/.test(text),
+    };
+}
+/**
+ * 新規タスクファイル生成専用のシリアライザ。フィールドは要件 §5.3 の表の順で出力する。
+ * depends_on は任意フィールドのため、空のときは行ごと省略する (§5.3 のファイル例に合わせる)。
+ */
+export function serializeTaskFile(frontmatter, body) {
+    const ordered = {
+        id: frontmatter.id,
+        title: frontmatter.title,
+        status: frontmatter.status,
+        assignee: frontmatter.assignee,
+        created_by: frontmatter.created_by,
+        priority: frontmatter.priority,
+        labels: frontmatter.labels,
+        blocked_type: frontmatter.blocked_type,
+        blocked_reason: frontmatter.blocked_reason,
+        ...(frontmatter.depends_on.length > 0 ? { depends_on: frontmatter.depends_on } : {}),
+        // milestone は任意フィールド。null のときは行ごと省略する (depends_on と同様・後方互換)
+        ...(frontmatter.milestone !== null ? { milestone: frontmatter.milestone } : {}),
+        // related_docs (波 VIII) は未指定 / 空なら行ごと省略 (既存ファイルと差分ゼロ・後方互換)
+        ...(frontmatter.related_docs !== undefined && frontmatter.related_docs.length > 0
+            ? { related_docs: frontmatter.related_docs }
+            : {}),
+        created: frontmatter.created,
+        updated: frontmatter.updated,
+    };
+    const yamlText = yaml.dump(ordered, {
+        schema: yaml.JSON_SCHEMA, // 日付を文字列のまま出力する (parse と対)
+        flowLevel: 1, // labels: [backend, auth] の flow 形式 (§5.3 の例)
+        lineWidth: -1, // 長い title を折り返さない
+        noRefs: true,
+    });
+    return `---\n${yamlText}---\n${body}`;
+}