phasegate 0.191.0 → 0.222.0

package/scripts/harness/validator-system/infrastructure/adapters/file-system-coverage-attestation-verification-adapter.ts

@@ -0,0 +1,165 @@
+// @unit validator-system
+// @layer infrastructure
+// @work-item-id WI-268
+
+import { readdir, readFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import type {
+  CoverageAttestationVerificationCollectResult,
+  CoverageAttestationVerificationPolicyPort,
+} from "../../domain/ports/coverage-attestation-verification-policy-port.js";
+import type { AttestationReference } from "../../domain/value-objects/attestation-verification-report.js";
+
+const COVERAGE_REPORT_FILE = "coverage_report.md";
+const CONSTRUCTION_REL = join("docs", "product", "construction");
+const LEGACY_MARKER = /<!--\s*@coverage-gating:\s*ungated-legacy\s*-->/;
+/** `<!-- @attestation <id> -->` の id を捕捉する（1 行内複数を許容）。 */
+const ATTESTATION_REF_GLOBAL = /<!--\s*@attestation\s+([^\s>-][^>]*?)\s*-->/g;
+const DEFAULT_MATRIX_PATH = ".harness/requirement-test-matrix.json";
+
+interface MatrixTestReference {
+  readonly filePath?: string;
+}
+
+interface MatrixAcMapping {
+  readonly testReferences?: readonly MatrixTestReference[];
+}
+
+interface MatrixStory {
+  readonly storyId?: string;
+  readonly storyMappings?: readonly MatrixAcMapping[];
+  readonly acMappings?: readonly MatrixAcMapping[];
+}
+
+/**
+ * WI-268 / ADR-030 §Decision.1・§Decision.3.②（第2段） — L3-007 の走査・解決アダプタ。
+ *
+ * `docs/product/construction/*​/coverage_report.md` を cwd 起点で走査し（targetPaths 非依存の
+ * corpus 走査。L2-016 と同様に自前でファイル探索する）、ungated-legacy マーカー付きファイルを除外して
+ * `<!-- @attestation <id> -->` 参照を抽出する。
+ *
+ * 参照が 1 件以上ある場合のみ requirement-test-matrix を読み、resolvable scope
+ * （storyId 存在 かつ testReferences >= 1 の story-id 集合）を解決する。matrix 不在・parse 不能は
+ * fail-closed（matrixError を返す）。参照 0 件なら matrix を読まず空 evidence + matrixError=null。
+ */
+export class FileSystemCoverageAttestationVerificationAdapter
+  implements CoverageAttestationVerificationPolicyPort
+{
+  constructor(
+    private readonly projectRoot: string,
+    private readonly matrixFilePath: string = DEFAULT_MATRIX_PATH,
+  ) {}
+
+  async collect(): Promise<CoverageAttestationVerificationCollectResult> {
+    const references = await this.collectReferences();
+
+    // 参照が 1 件も無ければ matrix を読みに行かず PASS（最小副作用）。
+    if (references.length === 0) {
+      return Object.freeze({
+        references: Object.freeze([]),
+        evidence: { resolvableScopeIds: new Set<string>() },
+        matrixError: null,
+      });
+    }
+
+    const resolved = await this.resolveScopeEvidence();
+    if (resolved.error !== null) {
+      // 参照ありで matrix を読めない → fail-closed。
+      return Object.freeze({
+        references: Object.freeze(references),
+        evidence: { resolvableScopeIds: new Set<string>() },
+        matrixError: resolved.error,
+      });
+    }
+
+    return Object.freeze({
+      references: Object.freeze(references),
+      evidence: { resolvableScopeIds: resolved.scopeIds },
+      matrixError: null,
+    });
+  }
+
+  private async collectReferences(): Promise<AttestationReference[]> {
+    const constructionRoot = join(this.projectRoot, CONSTRUCTION_REL);
+    let unitDirs: string[];
+    try {
+      const entries = await readdir(constructionRoot, { withFileTypes: true });
+      unitDirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    } catch {
+      return [];
+    }
+
+    const references: AttestationReference[] = [];
+    for (const unitDir of unitDirs) {
+      const filePath = join(constructionRoot, unitDir, COVERAGE_REPORT_FILE);
+      let content: string;
+      try {
+        content = await readFile(filePath, "utf-8");
+      } catch {
+        continue;
+      }
+      const relPath = `${CONSTRUCTION_REL.replace(/\\/g, "/")}/${unitDir}/${COVERAGE_REPORT_FILE}`;
+      this.parseReferences(relPath, content, references);
+    }
+    return references;
+  }
+
+  /** ungated-legacy マーカー付きファイルは免除。それ以外は各 @attestation 参照を抽出する。 */
+  private parseReferences(path: string, content: string, out: AttestationReference[]): void {
+    const lines = content.split(/\r?\n/);
+    if (lines.some((line) => LEGACY_MARKER.test(line))) return;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      ATTESTATION_REF_GLOBAL.lastIndex = 0;
+      let match: RegExpExecArray | null = ATTESTATION_REF_GLOBAL.exec(line);
+      while (match !== null) {
+        const id = match[1].trim();
+        if (id.length > 0) {
+          out.push({ id, sourcePath: path, lineNumber: i + 1 });
+        }
+        match = ATTESTATION_REF_GLOBAL.exec(line);
+      }
+    }
+  }
+
+  private async resolveScopeEvidence(): Promise<{ scopeIds: Set<string>; error: string | null }> {
+    const relativeOrAbsolute = this.matrixFilePath.length > 0 ? this.matrixFilePath : DEFAULT_MATRIX_PATH;
+    const absPath = isAbsolute(relativeOrAbsolute)
+      ? relativeOrAbsolute
+      : join(this.projectRoot, relativeOrAbsolute);
+
+    let parsed: unknown;
+    try {
+      const raw = await readFile(absPath, "utf-8");
+      parsed = JSON.parse(raw);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        scopeIds: new Set<string>(),
+        error: `requirement-test-matrix を読み込めません（L3-007 は fail-closed）: ${relativeOrAbsolute}: ${message}`,
+      };
+    }
+
+    const scopeIds = new Set<string>();
+    for (const story of this.extractStories(parsed)) {
+      const storyId = story.storyId;
+      if (!storyId) continue;
+      const mappings = story.storyMappings ?? story.acMappings ?? [];
+      const hasTestRef = mappings.some((ac) => (ac.testReferences?.length ?? 0) > 0);
+      if (hasTestRef) scopeIds.add(storyId);
+    }
+    return { scopeIds, error: null };
+  }
+
+  private extractStories(parsed: unknown): readonly MatrixStory[] {
+    if (typeof parsed !== "object" || parsed === null) return [];
+    const obj = parsed as { stories?: unknown; storyMappings?: unknown };
+    const raw = Array.isArray(obj.stories)
+      ? obj.stories
+      : Array.isArray(obj.storyMappings)
+        ? obj.storyMappings
+        : [];
+    return raw as readonly MatrixStory[];
+  }
+}

package/scripts/harness/validator-system/infrastructure/adapters/file-system-injection-scan-adapter.ts

@@ -0,0 +1,82 @@
+// @unit validator-system
+// @layer infrastructure
+// @work-item-id WI-259
+
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { InjectionScanPolicyPort } from "../../domain/ports/injection-scan-policy-port.js";
+import type { InjectionScanTarget } from "../../domain/value-objects/injection-scan-report.js";
+
+const SKILLS_DIR = "skills";
+const SKILL_FILE = "SKILL.md";
+const AGENT_CONTEXT_REL = join("docs", "templates", "agent-context");
+
+/** 固定パスの指示搭載ファイル（cwd 相対）。存在しなければ skip。 */
+const FIXED_FILES: readonly string[] = ["CLAUDE.md", "AGENTS.md", join(".claude", "settings.json")];
+
+/**
+ * WI-259 / ADR-030 §Decision.3.④ — advisory インジェクションスキャナ（L3-006）の走査アダプタ。
+ *
+ * 指示搭載ファイル群を cwd 起点で列挙・読み込みして InjectionScanTarget[] を返す
+ * （targetPaths 非依存の corpus 走査。L2-016 と同様に自前でファイル探索する）:
+ * - `skills/*​/SKILL.md`（readdir）
+ * - `CLAUDE.md` / `AGENTS.md` / `.claude/settings.json`（固定パス）
+ * - `docs/templates/agent-context/*.md`（readdir）
+ *
+ * 不在ファイルは黙って skip する。path は project-relative（posix 区切り）で報告する。
+ */
+export class FileSystemInjectionScanAdapter implements InjectionScanPolicyPort {
+  constructor(private readonly projectRoot: string) {}
+
+  async collect(): Promise<readonly InjectionScanTarget[]> {
+    const targets: InjectionScanTarget[] = [];
+
+    // skills/*/SKILL.md
+    const skillsRoot = join(this.projectRoot, SKILLS_DIR);
+    let skillDirs: string[] = [];
+    try {
+      const entries = await readdir(skillsRoot, { withFileTypes: true });
+      skillDirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    } catch {
+      skillDirs = [];
+    }
+    for (const dir of skillDirs) {
+      const relPath = `${SKILLS_DIR}/${dir}/${SKILL_FILE}`;
+      const target = await this.readTarget(join(skillsRoot, dir, SKILL_FILE), relPath);
+      if (target) targets.push(target);
+    }
+
+    // docs/templates/agent-context/*.md
+    const agentContextRoot = join(this.projectRoot, AGENT_CONTEXT_REL);
+    let agentContextFiles: string[] = [];
+    try {
+      const entries = await readdir(agentContextRoot, { withFileTypes: true });
+      agentContextFiles = entries.filter((e) => e.isFile() && e.name.endsWith(".md")).map((e) => e.name);
+    } catch {
+      agentContextFiles = [];
+    }
+    for (const name of agentContextFiles) {
+      const relPath = `${AGENT_CONTEXT_REL.replace(/\\/g, "/")}/${name}`;
+      const target = await this.readTarget(join(agentContextRoot, name), relPath);
+      if (target) targets.push(target);
+    }
+
+    // 固定パス
+    for (const rel of FIXED_FILES) {
+      const posixRel = rel.replace(/\\/g, "/");
+      const target = await this.readTarget(join(this.projectRoot, rel), posixRel);
+      if (target) targets.push(target);
+    }
+
+    return Object.freeze(targets);
+  }
+
+  private async readTarget(absPath: string, relPath: string): Promise<InjectionScanTarget | null> {
+    try {
+      const content = await readFile(absPath, "utf-8");
+      return { path: relPath, content };
+    } catch {
+      return null;
+    }
+  }
+}

package/skills/README.md

@@ -1,6 +1,6 @@
 # Skills ディレクトリ
 
-このディレクトリには、AIエージェントの共有スキル定義が含まれています。現在の配布対象は 30 skills です。公開一覧は `docs/guide/skills-overview.md`、setup lifecycle の管理対象は `docs/guide/setup-artifacts.md` を正とします。<!-- @work-item-id WI-154 -->
+このディレクトリには、AIエージェントの共有スキル定義が含まれています。現在の配布対象は 29 skills です。公開一覧は `docs/guide/skills-overview.md`、setup lifecycle の管理対象は `docs/guide/setup-artifacts.md` を正とします。<!-- @work-item-id WI-154 -->
 
 ## ディレクトリ構成と同期
 

package/skills/codebase-mapper/SKILL.md

@@ -161,4 +161,4 @@ unit-c
 |--------------|------|
 | `npx phasegate lint` | L1 archgateルールの全体スキャン |
 | `consistency-checker` | マップ生成後の設計文書整合性確認 |
-| `doc-freshness-checker` | マップと設計文書の鮮度を合わせて確認 |
+| `doc-health-checker` | マップと設計文書の鮮度・ポインタ有効性を合わせて確認 |

package/skills/consistency-checker/references//343/203/201/343/202/247/343/203/203/343/202/257/343/203/252/343/202/271/343/203/210.md

@@ -50,7 +50,7 @@
 
 ```
 # ストーリーID抽出（マークダウンテーブルから）
-# {storyIdPattern} はプロジェクトのストーリーID正規表現（例: US-[0-9]+）
+# {storyIdPattern} はプロジェクトのストーリーID正規表現（phasegate 既定は H[F0-9][0-9]*-[0-9]{2}）
 grep -oE '{storyIdPattern}' {userStoriesPath}
 
 # Unit内のストーリー参照抽出

package/skills/doc-health-checker/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: doc-health-checker
+kind: advisory
+description: 設計文書の健全性（鮮度 + ポインタ有効性）を L4 バリデータ CLI で診断・対処するスキル。`npx phasegate p2:check-freshness`（鮮度・code-design drift, L4-004）と `npx phasegate p2:validate-pointers`（壊れたファイルパスポインタ, L4-005）をラップし、結果を解釈して修正アクションを提案する。使用タイミング:「設計文書が古くなっていないか確認して」「ドキュメントの鮮度チェック」「設計とコードの乖離を調べて」「ドキュメントのリンク切れを確認して」「broken pointer を探して」「設計文書の参照が正しいか確認して」「L4 doc health チェック」など。
+model: sonnet
+review: opus
+languages: [typescript]
+---
+
+# Doc Health Checker
+
+## 目的
+
+設計文書の健全性を 2 つの観点で機械的に検証し、結果を解釈して修正アクションを提案する advisory スキル。旧 `doc-freshness-checker`（鮮度）と旧 `pointer-validator`（ポインタ有効性）を統合したもの。
+
+1. **鮮度（freshness）— L4-004**: 設計文書の最終更新が古すぎないか、コード変更と設計文書の乖離（code-design drift）がないかを検出する。`npx phasegate p2:check-freshness` をラップする。
+2. **ポインタ有効性（pointer validity）— L4-005**: 設計文書内で参照されているファイルパスポインタが実在するか（broken pointer）を検出する。`npx phasegate p2:validate-pointers` をラップする。
+
+いずれも L4 バリデータの CLI 拡張であり、本スキルは CLI を実行して結果を解釈し、ユーザーに対処案を提示する。
+
+> **重要（CLI 名の正）**: コマンドは必ず `p2:` 接頭辞付きで呼ぶ。無接頭辞の `phasegate check-freshness` / `phasegate validate-pointers` は **存在しない誤った表記**（旧スキルの記載は誤りだった）。正しくは `npx phasegate p2:check-freshness` / `npx phasegate p2:validate-pointers`。
+
+## 対象読者・使いどころ
+
+- 設計文書（`docs/product/construction/` や `docs/inception/` 配下の `.md`）が実装から取り残されていないか、参照リンクが壊れていないかを点検したいとき。
+- リリース前・大規模リファクタ後・Unit 完了時のドキュメント健全性確認。
+- 軽量チェックのため、鮮度とポインタの両方をまとめて走らせるのが基本運用。
+
+## CLI リファレンス
+
+### 1. 鮮度チェック — `p2:check-freshness`（L4-004）
+
+```bash
+npx phasegate p2:check-freshness [--pattern <glob>] [--format text|json] [--dry-run]
+```
+
+| オプション | 意味 |
+|-----------|------|
+| `--pattern <glob>` | 対象ファイルの glob（未指定時は config の設計文書パスが対象） |
+| `--format text\|json` | 出力形式（デフォルト `text`） |
+| `--dry-run` | 副作用なしで診断のみ |
+
+`CheckDocFreshnessOutput` の主なフィールド:
+
+| フィールド | 意味 |
+|-----------|------|
+| `results[].status` | `ok` / `warn` / `error` |
+| `results[].documentPath` | チェック対象ファイル |
+| `results[].daysSinceUpdate` | 最終更新からの日数 |
+| `results[].threshold` | 設定閾値 |
+| `summary.error` | error 件数（exit code 1 になる） |
+| `summary.warn` | warn 件数 |
+
+**exit code**: `summary.error > 0` なら 1、それ以外 0。
+
+### 2. ポインタ検証 — `p2:validate-pointers`（L4-005）
+
+```bash
+npx phasegate p2:validate-pointers [--pattern <glob>] [--include-urls] [--format text|json]
+```
+
+| オプション | 意味 |
+|-----------|------|
+| `--pattern <glob>` | 対象ファイルの glob（未指定時は config の設計文書パスが対象） |
+| `--include-urls` | URL ポインタ（`http(s)://`）も検証対象に含める（デフォルトは file-path のみ） |
+| `--format text\|json` | 出力形式（デフォルト `text`） |
+
+検出対象ポインタ: Markdown `[text](path)` リンク / `@file:` `@ref:` / `filePath:` フィールドのパス参照。`http(s)://` URL は `--include-urls` 指定時のみ検証。
+
+`ValidateDocPointersOutput` の主なフィールド:
+
+| フィールド | 意味 |
+|-----------|------|
+| `results[].documentPath` | ポインタを含む文書 |
+| `results[].pointerTarget` | 参照先パス |
+| `results[].pointerType` | `file-path` / `url` |
+| `results[].isResolvable` | 解決可能かどうか |
+| `results[].errorMessage` | エラー内容（null なら正常） |
+| `summary.brokenPointers` | broken 件数 |
+| `summary.skippedUrlPointers` | スキップした URL 件数 |
+| `passed` | 全ポインタ有効なら true |
+
+**exit code**: `passed` なら 0、broken があれば 1。
+
+> **注意**: このスキルの CLI には自動修正フラグ（`--fix`）は存在しない。ポインタ修正は結果を解釈したうえで手動（`Edit`）で行う。
+
+## ワークフロー
+
+軽量チェックのため単一フェーズで実行する。鮮度とポインタは独立なので、必要に応じて片方だけ／両方を走らせる。
+
+### Step 1: 実行
+
+```bash
+# 両方まとめて（推奨）
+npx phasegate p2:check-freshness --format json
+npx phasegate p2:validate-pointers --format json
+```
+
+大量に broken が出そうな大規模リポジトリでは `--pattern` でスコープを絞って段階実行する。
+
+### Step 2: 結果の解釈とアクション
+
+**鮮度（freshness）**:
+
+| 状態 | 推奨アクション |
+|------|--------------|
+| `error`（閾値超過 / drift 疑い） | `cascade-updater` で上位設計文書を更新、コードと設計の乖離を解消 |
+| `warn`（閾値近接） | 設計文書の内容を確認し、必要に応じて更新 |
+| `ok` | 対応不要 |
+
+**ポインタ（pointer）**: broken の原因別に対処する。
+
+| broken 原因 | 推奨アクション |
+|-----------|--------------|
+| ファイルが移動された | ポインタのパスを新パスに更新（`Edit`） |
+| ファイルが削除された | ポインタを削除 or 代替ファイルに変更 |
+| タイポ | パス修正 |
+| 未作成ファイルへの前方参照 | 意図的なら `[TODO]` マーカーを付ける |
+
+修正後は同じコマンドを再実行して 0 件（`passed: true` / `summary.error: 0`）を確認する。
+
+### 出力フォーマット（ユーザー報告例）
+
+```markdown
+# Doc Health チェック結果
+
+## 鮮度（p2:check-freshness / L4-004）
+- 総ドキュメント数: N ／ ok: N / warn: N / error: N
+### 要対応（error）
+| ファイル | 最終更新 | 閾値超過日数 | 推奨アクション |
+|---------|---------|------------|--------------|
+
+## ポインタ（p2:validate-pointers / L4-005）
+- チェック文書数: N ／ broken: N / URL(スキップ): N
+### Broken Pointers（要修正）
+| 文書ファイル | 参照先 | エラー | 推奨修正 |
+|------------|--------|--------|---------|
+
+## 次のアクション
+（error があれば cascade-updater、broken があれば該当ポインタの Edit を提案）
+```
+
+## 関連スキル
+
+| スキル | 用途 |
+|-------|------|
+| `cascade-updater` | 鮮度 error が出た設計文書の連鎖更新 |
+| `consistency-checker` | 文書間の内容整合性チェック（健全性修正後の確認） |

package/skills/release-publisher/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: release-publisher
+kind: advisory
+description: phasegate のリリース手順（version bump / git tag / npm publish）の厳格ガイド。この npm アカウントは security key (FIDO/WebAuthn) 認証のため publish は必ず `npm publish --auth-type=web`。使用タイミング:「リリースして」「publish して」「npm に上げて」「バージョンを上げてタグを打って」「EOTP エラーが出た」「npm publish が認証で失敗する」など、version bump・タグ付与・npm publish・publish 認証トラブルに関わる場面。
+model: sonnet
+review: opus
+languages: [typescript]
+---
+
+# Release Publisher
+
+## 目的
+
+phasegate パッケージのリリース（version bump → git tag → npm publish）を、誤操作・認証事故なしに完遂するための厳格手順ガイド（advisory）。正となる規範は `CLAUDE.md` の「バージョニングルール」「npm publish ルール」節、および `DEVELOPMENT.md` の「Versioning and Release」「Troubleshooting npm publish authentication」節。本スキルはそれらを実行手順として展開する。
+
+## 絶対ルール（違反禁止）
+
+1. **この npm アカウントは security key (FIDO/WebAuthn) 認証**。publish は必ず:
+
+   ```bash
+   npm publish --auth-type=web   # ブラウザで security key 認証 → publish
+   ```
+
+2. **禁止事項**:
+   - `npm publish --otp=<code>` を実行すること（`--otp` フラグは TOTP 専用。security key 認証では拒否される）
+   - ユーザーに OTP を尋ねること
+   - authenticator アプリの参照を提案すること
+3. **EOTP エラーが出たら、OTP を聞き返さずに直ちに `--auth-type=web` に切り替える。**
+4. **コミットごとに `package.json` の minor バージョンを上げる**（`"0.X.0"` → `"0.(X+1).0"`）。タグ `vX.Y.Z` を付与して push する。
+
+## リリース手順
+
+### Step 1: 事前クロスチェック（3点照合）
+
+local の `package.json` は npm registry と乖離しうる（過去に registry v0.32.0 / local v0.38.0 の乖離事例あり）。publish 前に必ず 3 つを照合する:
+
+```bash
+npm view phasegate version       # registry latest
+git tag --list | tail -5         # local tags
+grep '"version"' package.json    # local version
+```
+
+乖離があれば原因（publish 漏れ / tag 漏れ）を特定してから進む。
+
+### Step 2: version bump と CHANGELOG
+
+1. `package.json` の `version` を minor bump（例: `0.5.0` → `0.6.0`）
+2. `CHANGELOG.md` にエントリを追加
+
+### Step 3: commit / tag / push
+
+```bash
+git add package.json CHANGELOG.md
+git commit -m "fix: vX.Y.Z — description"
+git tag vX.Y.Z
+git push origin main --tags
+```
+
+### Step 4: 認証確認と dry-run
+
+```bash
+npm whoami                # 未ログインなら: npm login --auth-type=web
+npm publish --dry-run     # tarball の内容を確認
+```
+
+### Step 5: publish
+
+```bash
+npm publish --auth-type=web
+```
+
+ブラウザが開くので security key で認証すると publish が完了する。
+
+## 認証トラブルシューティング
+
+`npm publish` の挙動はアカウントの 2FA モードに依存する:
+
+| 2FA モード | publish の挙動 | 対処 |
+|---|---|---|
+| 無効 | そのまま通る | `npm publish` |
+| TOTP (authenticator アプリ) | `EOTP` エラー → OTP 要求 | `npm publish --otp=<6桁>` |
+| Email OTP (Enhanced Login Verification) | `EOTP` エラー → メールでコード送付 | 受信箱を確認して `--otp=<6桁>` |
+| **Security key / Passkey (FIDO/WebAuthn)** ← このアカウント | `EOTP` エラー（`--otp` は TOTP 専用のため使用不可） | **`npm publish --auth-type=web`** — ブラウザが開き、キーで認証して publish 完了 |
+
+**security key アカウントの鉄則**: 常に `--auth-type=web` を使う。`--otp` フラグは TOTP 専用であり拒否される。EOTP エラーを見たら OTP を探しに行かず、直ちに `--auth-type=web` で再実行する。
+
+**CI / 自動化**: https://www.npmjs.com/settings/&lt;username&gt;/tokens から **Granular Access Token**（scope: 対象パッケージ、permissions: Read and write、Bypass 2FA: enabled）を発行し、`.npmrc` の `//registry.npmjs.org/:_authToken=<TOKEN>` または `NPM_TOKEN` 環境変数で注入する。
+
+## よくある失敗と回避
+
+| 症状 | 原因 | 回避 |
+|------|------|------|
+| `EOTP` エラーで停止し OTP を探し始める | `--otp` が TOTP 専用であることを知らない | 直ちに `--auth-type=web` に切替（OTP を聞き返さない） |
+| registry と local version の乖離 | publish 漏れ・tag 漏れの蓄積 | Step 1 の 3 点照合を必ず実施 |
+| tag なしで publish | 手順の省略 | Step 3 の tag + `--tags` push を省略しない |
+| CHANGELOG 未更新のまま publish | version bump のみ実施 | Step 2 で CHANGELOG エントリ追加を必ずセットで行う |
+
+## 参照
+
+- `CLAUDE.md` — 「バージョニングルール（必須）」「npm publish ルール（必須）」
+- `DEVELOPMENT.md` — 「Versioning and Release」「Troubleshooting npm publish authentication」「Cross-check before publishing」