phasegate 0.191.0 → 0.212.0

package/scripts/harness/validator-system/domain/value-objects/injection-scan-report.ts

@@ -0,0 +1,55 @@
+// @unit validator-system
+// @layer domain
+// @work-item-id WI-259
+
+/**
+ * WI-259 / ADR-030 §Decision.3.④ — advisory インジェクションスキャナ（L3-006）用ドメインモデル。
+ *
+ * 指示搭載ファイルに対する既知インジェクションパターンの検出結果を表す value-object 群。
+ * 全 finding は severity='warning'（advisory）。error / violation は構造上生成しない（§4.(b)）。
+ */
+
+/** 検出種別。 */
+export type InjectionFindingKind =
+  | "instruction-override"
+  | "invisible-unicode"
+  | "base64-blob"
+  | "html-comment-instruction";
+
+/** 1 走査対象ファイル（infra が解決）。 */
+export interface InjectionScanTarget {
+  /** project-relative パス（報告用）。 */
+  readonly path: string;
+  readonly content: string;
+}
+
+/** 1 件の検出。severity は常に 'warning'。 */
+export interface InjectionFinding {
+  readonly kind: InjectionFindingKind;
+  readonly severity: "warning";
+  readonly sourcePath: string;
+  /** 1 起点の行番号。 */
+  readonly lineNumber: number;
+  readonly message: string;
+  readonly suggestion: string;
+}
+
+/**
+ * スキャン判定レポート。findings はすべて warning（advisory）。
+ */
+export class InjectionScanReport {
+  readonly findings: readonly InjectionFinding[];
+
+  private constructor(findings: readonly InjectionFinding[]) {
+    this.findings = Object.freeze([...findings]);
+    Object.freeze(this);
+  }
+
+  static create(findings: readonly InjectionFinding[]): InjectionScanReport {
+    return new InjectionScanReport(findings);
+  }
+
+  hasFindings(): boolean {
+    return this.findings.length > 0;
+  }
+}

package/scripts/harness/validator-system/domain/value-objects/validator-id.ts

@@ -11,13 +11,15 @@
  * WI-156 で L4-006 を追加
  * WI-222 (HF2-05) で L4-007（ac-level-traceability, default-OFF advisory）を追加
  * WI-227 (H16-03) で L3-005（ac-bound-coverage, default-OFF fail-closed）を追加
+ * WI-258 (ADR-030 §Decision.3.②) で L2-016（coverage-attestation-gating, fail-closed）を追加
+ * WI-259 (ADR-030 §Decision.3.④) で L3-006（injection-scan, advisory warning-only）を追加
  */
 
 export class InvalidValidatorIdError extends Error {
   readonly invalidValue: string;
   constructor(raw: string) {
     super(`Invalid validator ID: "${raw}". Must be one of the registered valid IDs.`);
-    this.name = 'InvalidValidatorIdError';
+    this.name = "InvalidValidatorIdError";
     this.invalidValue = raw;
   }
 }
@@ -26,38 +28,40 @@ const VALIDATOR_ID_PATTERN = /^L[0-4]-\d{3}$/;
 
 /** バリデータID -> バリデータ名のマップ */
 const VALIDATOR_NAME_MAP: Record<string, string> = {
-  'L1-017': 'it-test-mock-detection',
-  'L1-018': 'stub-comment-detection',
-  'L2-001': 'phase-gate',
-  'L2-002': 'metadata',
-  'L2-003': 'test-quality',
-  'L2-013': 'cli-e2e-test-existence',
-  'L2-014': 'work-item-status-staleness',
-  'L2-015': 'contract-traceability-coverage',
-  'L3-001': 'security',
-  'L3-002': 'performance',
-  'L3-003': 'coverage',
-  'L3-004': 'nyquist',
-  'L3-005': 'ac-bound-coverage',
-  'L4-001': 'drift-detect',
-  'L4-002': 'consistency-check',
-  'L4-003': 'dead-code',
-  'L4-004': 'doc-freshness',
-  'L4-005': 'pointer-validation',
-  'L4-006': 'skill-catalog-drift',
-  'L4-007': 'ac-level-traceability',
+  "L1-017": "it-test-mock-detection",
+  "L1-018": "stub-comment-detection",
+  "L2-001": "phase-gate",
+  "L2-002": "metadata",
+  "L2-003": "test-quality",
+  "L2-013": "cli-e2e-test-existence",
+  "L2-014": "work-item-status-staleness",
+  "L2-015": "contract-traceability-coverage",
+  "L2-016": "coverage-attestation-gating",
+  "L3-001": "security",
+  "L3-002": "performance",
+  "L3-003": "coverage",
+  "L3-004": "nyquist",
+  "L3-005": "ac-bound-coverage",
+  "L3-006": "injection-scan",
+  "L4-001": "drift-detect",
+  "L4-002": "consistency-check",
+  "L4-003": "dead-code",
+  "L4-004": "doc-freshness",
+  "L4-005": "pointer-validation",
+  "L4-006": "skill-catalog-drift",
+  "L4-007": "ac-level-traceability",
 };
 
 /** バリデータ名 -> バリデータID の逆引きマップ */
 const NAME_TO_ID_MAP: Record<string, string> = {
   ...Object.fromEntries(Object.entries(VALIDATOR_NAME_MAP).map(([id, name]) => [name, id])),
-  'drift-detector': 'L4-001',
-  'consistency-checker': 'L4-002',
-  'dead-code-detector': 'L4-003',
-  'doc-freshness-checker': 'L4-004',
-  'pointer-validator': 'L4-005',
-  'skill-catalog-drift': 'L4-006',
-  'ac-level-traceability': 'L4-007',
+  "drift-detector": "L4-001",
+  "consistency-checker": "L4-002",
+  "dead-code-detector": "L4-003",
+  "doc-freshness-checker": "L4-004",
+  "pointer-validator": "L4-005",
+  "skill-catalog-drift": "L4-006",
+  "ac-level-traceability": "L4-007",
 };
 
 /** 有効なValidatorID集合 */
@@ -65,12 +69,12 @@ const VALID_IDS = new Set(Object.keys(VALIDATOR_NAME_MAP));
 
 export class ValidatorId {
   readonly value: string;
-  readonly layer: 'L0' | 'L1' | 'L2' | 'L3' | 'L4';
+  readonly layer: "L0" | "L1" | "L2" | "L3" | "L4";
   readonly sequence: string;
 
   private constructor(value: string) {
     this.value = value;
-    this.layer = value.substring(0, 2) as 'L0' | 'L1' | 'L2' | 'L3' | 'L4';
+    this.layer = value.substring(0, 2) as "L0" | "L1" | "L2" | "L3" | "L4";
     this.sequence = value.substring(3);
     Object.freeze(this);
   }
@@ -93,7 +97,7 @@ export class ValidatorId {
     return new ValidatorId(id);
   }
 
-  getLayer(): 'L0' | 'L1' | 'L2' | 'L3' | 'L4' {
+  getLayer(): "L0" | "L1" | "L2" | "L3" | "L4" {
     return this.layer;
   }
 

package/scripts/harness/validator-system/infrastructure/adapters/adr-foundation-reference-adapter.ts

@@ -4,9 +4,12 @@
  *
  * AdrFoundationReferenceAdapter — AdrReferencePort実装
  */
-import type { AdrReferencePort, AdrMetadata } from '../../domain/ports/adr-reference-port.js';
+import * as path from "node:path";
+import type { AdrMetadata, AdrReferencePort } from "../../domain/ports/adr-reference-port.js";
 
 export class AdrFoundationReferenceAdapter implements AdrReferencePort {
+  constructor(private readonly rootDir: string = process.cwd()) {}
+
   async exists(adrRef: string): Promise<boolean> {
     try {
       const adr = await this.findAdr(adrRef);
@@ -35,19 +38,22 @@ export class AdrFoundationReferenceAdapter implements AdrReferencePort {
   }
 
   private async findAdr(adrRef: string): Promise<{
-    readonly getFrontmatter: () => { readonly title: string; readonly status: { readonly value: AdrMetadata['status'] } };
+    readonly getFrontmatter: () => {
+      readonly title: string;
+      readonly status: { readonly value: AdrMetadata["status"] };
+    };
     readonly toAdrRef: () => string;
   } | null> {
-    const { createAdrFoundationModule } = await import('../../../adr-foundation/composition-root.js');
-    const { AdrId } = await import('../../../adr-foundation/domain/value-objects/adr-id.js');
-    const mod = createAdrFoundationModule(process.cwd());
+    const { createAdrFoundationModule } = await import("../../../adr-foundation/composition-root.js");
+    const { AdrId } = await import("../../../adr-foundation/domain/value-objects/adr-id.js");
+    const mod = createAdrFoundationModule(path.join(this.rootDir, "docs", "ADR"));
     const repository = mod.adrRepository;
 
-    if ('findById' in repository && typeof repository.findById === 'function') {
+    if ("findById" in repository && typeof repository.findById === "function") {
       return repository.findById(AdrId.create(adrRef));
     }
 
-    if ('findAll' in repository && typeof repository.findAll === 'function') {
+    if ("findAll" in repository && typeof repository.findAll === "function") {
       const adrs = await repository.findAll();
       return adrs.find((adr) => adr.toAdrRef() === adrRef) ?? null;
     }

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

@@ -0,0 +1,87 @@
+// @unit validator-system
+// @layer infrastructure
+// @work-item-id WI-258
+
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { CoverageAttestationGatingPolicyPort } from "../../domain/ports/coverage-attestation-gating-policy-port.js";
+import type { CoverageClaim, CoverageReportGatingModel } from "../../domain/value-objects/coverage-gating-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*-->/;
+const ATTESTATION_REF = /<!--\s*@attestation\b/;
+const CHECKMARK = "✅"; // ✅
+const COMMENT_LINE = /^\s*<!--/;
+
+/**
+ * WI-258 / ADR-030 §Decision.3.② — coverage-attestation-gating (L2-016) の走査アダプタ。
+ *
+ * `docs/product/construction/*​/coverage_report.md` を cwd 起点で走査し（targetPaths 非依存の
+ * corpus 走査。L2-014 と同様に自前でファイル探索する）、各ファイルを CoverageReportGatingModel 化する。
+ *
+ * - legacy マーカー: `<!-- @coverage-gating: ungated-legacy -->` の有無。
+ * - ✅ claim: `✅` を含む行。同一行に `<!-- @attestation ... -->` があるか、
+ *   直前の連続コメント行に `@attestation` があれば hasAttestationRef=true。
+ */
+export class FileSystemCoverageAttestationGatingAdapter implements CoverageAttestationGatingPolicyPort {
+  constructor(private readonly projectRoot: string) {}
+
+  async collect(): Promise<readonly CoverageReportGatingModel[]> {
+    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 Object.freeze([]);
+    }
+
+    const models: CoverageReportGatingModel[] = [];
+    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;
+      }
+      // path は project-relative で報告する（メッセージの可搬性のため）。
+      const relPath = `${CONSTRUCTION_REL.replace(/\\/g, "/")}/${unitDir}/${COVERAGE_REPORT_FILE}`;
+      models.push(this.parse(relPath, content));
+    }
+    return Object.freeze(models);
+  }
+
+  private parse(path: string, content: string): CoverageReportGatingModel {
+    const lines = content.split(/\r?\n/);
+    const hasLegacyMarker = lines.some((line) => LEGACY_MARKER.test(line));
+
+    const claims: CoverageClaim[] = [];
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (!line.includes(CHECKMARK)) continue;
+      claims.push({
+        lineNumber: i + 1,
+        hasAttestationRef: this.hasAttestationRef(lines, i),
+      });
+    }
+
+    return { path, hasLegacyMarker, claims };
+  }
+
+  /**
+   * ✅ 行 index について attestation 参照があるか判定する。
+   * (1) 同一行にコメント参照、または
+   * (2) 直前の連続するコメント行のいずれかに `@attestation` 参照がある。
+   */
+  private hasAttestationRef(lines: readonly string[], index: number): boolean {
+    if (ATTESTATION_REF.test(lines[index])) return true;
+    for (let j = index - 1; j >= 0; j--) {
+      const prev = lines[j];
+      if (!COMMENT_LINE.test(prev)) break;
+      if (ATTESTATION_REF.test(prev)) return true;
+    }
+    return false;
+  }
+}

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」