phasegate 0.283.0 → 0.335.0

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

@@ -6,7 +6,7 @@
  * ConsistencyReport 値オブジェクト
  * 設計文書間のレイヤー整合性検証結果VO（L4-002専用）
  */
-import type { HarnessErrorLike } from './validation-result.js';
+import type { HarnessErrorLike } from "./validation-result.js";
 
 export interface MismatchPair {
   readonly expected: string;
@@ -48,10 +48,12 @@ export class ConsistencyReport {
   // ADR-017 / WI-094: error catalog の defaultSeverity: warning と整合
   toHarnessErrors(): readonly HarnessErrorLike[] {
     return this.mismatchPairs.map((pair) => ({
-      code: { value: 'L4-002', toString: () => 'L4-002' },
-      severity: { value: 'warning', toString: () => 'warning' },
+      code: { value: "L4-002", toString: () => "L4-002" },
+      severity: { value: "warning", toString: () => "warning" },
       message: `レイヤー整合性違反: expected "${pair.expected}" but got "${pair.actual}" at ${pair.location}`,
-      suggestion: pair.nextAction ?? '設計文書間のレイヤー依存方向を統一してください',
+      suggestion: pair.nextAction ?? "設計文書間のレイヤー依存方向を統一してください",
+      // WI-335: 文書間整合の回復は「どちらの記述が正か」の判断を伴う（ai-assisted）。
+      remediationType: "ai-assisted" as const,
     }));
   }
 }

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

@@ -5,9 +5,9 @@
  * DriftReport 値オブジェクト
  * 設計文書とコード実装の双方向乖離検出結果VO（L4-001専用）
  */
-import type { HarnessErrorLike } from './validation-result.js';
+import type { HarnessErrorLike } from "./validation-result.js";
 
-export type DriftDirection = 'design→code' | 'code→design';
+export type DriftDirection = "design→code" | "code→design";
 
 export interface DriftReportProps {
   readonly direction: DriftDirection;
@@ -29,14 +29,16 @@ export class DriftReport {
     this.direction = props.direction;
     this.unitName = props.unitName;
     this.element = props.element;
-    this.recommendation = props.recommendation ?? (props.description ?? '');
+    this.recommendation = props.recommendation ?? props.description ?? "";
     this.location = Object.freeze(props.location ?? {});
     Object.freeze(this);
   }
 
   static create(props: DriftReportProps): DriftReport {
-    if (props.direction !== 'design→code' && props.direction !== 'code→design') {
-      throw new Error(`Invalid DriftReport direction: "${props.direction}". Must be "design→code" or "code→design" (INV-10)`);
+    if (props.direction !== "design→code" && props.direction !== "code→design") {
+      throw new Error(
+        `Invalid DriftReport direction: "${props.direction}". Must be "design→code" or "code→design" (INV-10)`,
+      );
     }
     return new DriftReport(props);
   }
@@ -44,10 +46,13 @@ export class DriftReport {
   toHarnessError(): HarnessErrorLike {
     // ADR-017 / WI-094: error catalog の defaultSeverity: warning と整合
     return {
-      code: { value: 'L4-001', toString: () => 'L4-001' },
-      severity: { value: 'warning', toString: () => 'warning' },
+      code: { value: "L4-001", toString: () => "L4-001" },
+      severity: { value: "warning", toString: () => "warning" },
       message: `乖離検出 [${this.direction}] Unit: ${this.unitName}, Element: ${this.element}`,
       suggestion: this.recommendation,
+      // WI-335: design drift の解消は設計意図の理解が必要で機械適用不能。AI が設計文書を
+      // 読んで自己修正できる分類（ai-assisted）。
+      remediationType: "ai-assisted",
     };
   }
 

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

@@ -5,7 +5,7 @@
  * ValidationResult 値オブジェクト
  * バリデータ実行結果のスナップショット（不変）
  */
-import type { ValidatorId } from './validator-id.js';
+import type { ValidatorId } from "./validator-id.js";
 
 /** HarnessError の最小互換型（harness-error Unit の HarnessError との疎結合） */
 export interface HarnessErrorLike {
@@ -13,6 +13,12 @@ export interface HarnessErrorLike {
   readonly severity: { readonly value?: string; toString(): string };
   readonly message: string;
   readonly suggestion: string;
+  /**
+   * WI-335: suggestion の修復方式分類。未設定は 'manual' 扱い（機械適用可能と過剰宣言しない）。
+   * 'mechanical' を宣言したエラーは remediation-round-trip テストで
+   * 「エラー → suggestion を機械適用 → 再実行 → pass」が CI 保証される。
+   */
+  readonly remediationType?: "mechanical" | "ai-assisted" | "manual";
   [key: string]: unknown;
 }
 
@@ -49,10 +55,12 @@ export class ValidationResult {
       throw new Error(`ValidationResult durationMs must be >= 0 (got: ${props.durationMs})`);
     }
     if (props.passed && props.errors.length > 0) {
-      throw new Error('ValidationResult invariant violation: passed=true but errors is not empty (INV-5)');
+      throw new Error("ValidationResult invariant violation: passed=true but errors is not empty (INV-5)");
     }
     if (props.skipped && (!props.passed || props.errors.length > 0)) {
-      throw new Error('ValidationResult invariant violation: skipped=true requires passed=true and empty errors (INV-8)');
+      throw new Error(
+        "ValidationResult invariant violation: skipped=true requires passed=true and empty errors (INV-8)",
+      );
     }
     return new ValidationResult(props);
   }

package/scripts/harness/validator-system/infrastructure/adapters/file-system-security-pattern-scanner-adapter.ts

@@ -5,11 +5,12 @@
  *
  * FileSystemSecurityPatternScannerAdapter — SecurityPatternScannerPort実装
  */
-import type { SecurityPatternScannerPort } from '../../domain/ports/security-pattern-scanner-port.js';
-import type { HarnessErrorLike } from '../../domain/value-objects/validation-result.js';
-import { readFile } from 'node:fs/promises';
 
-const ALLOWLIST_MARKER = 'phasegate-allow-secret-fixture';
+import { readFile } from "node:fs/promises";
+import type { SecurityPatternScannerPort } from "../../domain/ports/security-pattern-scanner-port.js";
+import type { HarnessErrorLike } from "../../domain/value-objects/validation-result.js";
+
+const ALLOWLIST_MARKER = "phasegate-allow-secret-fixture";
 
 interface SecurityPattern {
   readonly ruleId: string;
@@ -18,15 +19,15 @@ interface SecurityPattern {
 }
 
 const SECURITY_PATTERNS: readonly SecurityPattern[] = Object.freeze([
-  { ruleId: 'secret.openai', pattern: /\b(?:sk|rk|sess)-[a-zA-Z0-9_-]{20,}\b/g, description: 'OpenAI token family' },
-  { ruleId: 'secret.github', pattern: /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g, description: 'GitHub token family' },
-  { ruleId: 'secret.aws-access-key', pattern: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, description: 'AWS access key id' },
-  { ruleId: 'secret.npm', pattern: /\bnpm_[A-Za-z0-9]{24,}\b/g, description: 'npm token family' },
-  { ruleId: 'secret.slack', pattern: /\bxox[abprs]-[A-Za-z0-9-]{20,}\b/g, description: 'Slack token family' },
+  { ruleId: "secret.openai", pattern: /\b(?:sk|rk|sess)-[a-zA-Z0-9_-]{20,}\b/g, description: "OpenAI token family" },
+  { ruleId: "secret.github", pattern: /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g, description: "GitHub token family" },
+  { ruleId: "secret.aws-access-key", pattern: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, description: "AWS access key id" },
+  { ruleId: "secret.npm", pattern: /\bnpm_[A-Za-z0-9]{24,}\b/g, description: "npm token family" },
+  { ruleId: "secret.slack", pattern: /\bxox[abprs]-[A-Za-z0-9-]{20,}\b/g, description: "Slack token family" },
   {
-    ruleId: 'secret.keyword-context',
+    ruleId: "secret.keyword-context",
     pattern: /\b(?:API_KEY|api_key|apikey|password|PASSWORD|passwd|secret|token)\b\s*[:=]\s*["'][^"']{8,}["']/g,
-    description: 'keyword-context secret',
+    description: "keyword-context secret",
   },
 ]);
 
@@ -39,8 +40,8 @@ export class FileSystemSecurityPatternScannerAdapter implements SecurityPatternS
 
     for (const filePath of targetPaths) {
       try {
-        const content = await readFile(filePath, 'utf-8');
-        const lines = content.split('\n');
+        const content = await readFile(filePath, "utf-8");
+        const lines = content.split("\n");
         lines.forEach((line, idx) => {
           // WI-120: allowlist は行/領域スコープ。以前はファイル内のどこかに
           // マーカーが 1 つでもあればファイル全体をスキップしていたため、同一
@@ -54,12 +55,14 @@ export class FileSystemSecurityPatternScannerAdapter implements SecurityPatternS
             pattern.lastIndex = 0;
             const matches = [...line.matchAll(pattern)];
             for (const match of matches) {
-              const secretValue = match[0] ?? '';
+              const secretValue = match[0] ?? "";
               findings.push({
-                code: { value: 'L3-001', toString: () => 'L3-001' },
-                severity: { value: 'error', toString: () => 'error' },
+                code: { value: "L3-001", toString: () => "L3-001" },
+                severity: { value: "error", toString: () => "error" },
                 message: `セキュリティ問題: ${description} (${ruleId}) at ${filePath}:${idx + 1} value=${redactSecret(secretValue)}`,
                 suggestion: `${ruleId}: 秘密情報は環境変数または秘密管理サービスを使用してください。fixture/docs のダミー値は ${ALLOWLIST_MARKER} を明示してください。`,
+                // WI-335: 秘密情報の無効化・ローテーション・保管方式の選定は人間の判断が必須（manual）。
+                remediationType: "manual",
               });
             }
           }
@@ -88,6 +91,6 @@ function isAllowlisted(line: string, previousLine: string | undefined): boolean
 
 function redactSecret(secretValue: string): string {
   const value = secretValue.trim();
-  if (value.length <= 8) return '<redacted>';
+  if (value.length <= 8) return "<redacted>";
   return `${value.slice(0, 3)}...<redacted:${value.length}>`;
 }

package/scripts/harness/validator-system/infrastructure/adapters/phase-dependency-phase-gate-policy-adapter.ts

@@ -4,8 +4,27 @@
  *
  * PhaseDependencyPhaseGatePolicyAdapter — PhaseGatePolicyPort実装
  */
-import type { PhaseGatePolicyPort } from '../../domain/ports/phase-gate-policy-port.js';
-import type { HarnessErrorLike } from '../../domain/value-objects/validation-result.js';
+import type { PhaseGatePolicyPort } from "../../domain/ports/phase-gate-policy-port.js";
+import type { HarnessErrorLike } from "../../domain/value-objects/validation-result.js";
+
+/**
+ * WI-357 (issue #29): `validate --layer L2` の失敗出力には従来
+ * 'phase gate prerequisites are not met' という事実の再掲しか載らず、
+ * 「何を作れば通るのか」がどの経路からも得られなかった。
+ * hook の block メッセージ側にしか復旧手順がないため、CLI から検証した
+ * エージェントは不足文書を推測で書くしかなくなる。
+ *
+ * 実行可能な復旧手順（scaffold コマンド）と、文書のセクション構成の在り処
+ * （skills/<skill>/SKILL.md、未配置なら `phasegate skills info`）を suggestion に載せる。
+ */
+export function buildPhaseGateRecoverySuggestion(unitName: string): string {
+  const unitArg = unitName.trim().length > 0 ? unitName.trim() : "<unit-id>";
+  return [
+    `不足している設計文書を scaffold で作成してください: npx phasegate scaffold-design --unit ${unitArg} --phase <logical|domain|uiux|unit-test|it-test> --apply`,
+    "各文書のセクション構成は導入先 repo の skills/<skill>/SKILL.md に記載されています（logical_design.md → skills/logical-designer/SKILL.md、domain_model.md → skills/domain-designer/SKILL.md、unit plan → skills/unit-designer/SKILL.md）。",
+    "skills/ が repo に無い場合は `npx phasegate skills info <skill-name>` で同じ内容を stdout から読めます。",
+  ].join("\n");
+}
 
 export class PhaseDependencyPhaseGatePolicyAdapter implements PhaseGatePolicyPort {
   async checkPrerequisites(context: { unitName: string; currentPhase: string }): Promise<{
@@ -18,11 +37,13 @@ export class PhaseDependencyPhaseGatePolicyAdapter implements PhaseGatePolicyPor
 
     try {
       // WI-085: paths config を phase-dependency-model に流入させる
-      const { createConfigFoundationModule } = await import('../../../config-foundation/composition-root.js');
-      const { toPhaseConfigSection } = await import('../../../config-foundation/application/mappers/phase-config-section-mapper.js');
+      const { createConfigFoundationModule } = await import("../../../config-foundation/composition-root.js");
+      const { toPhaseConfigSection } = await import(
+        "../../../config-foundation/application/mappers/phase-config-section-mapper.js"
+      );
       const configModule = createConfigFoundationModule();
       const resolvedConfig = await configModule.usecases.loadResolvedConfigUseCase.execute();
-      const { createPhaseDependencyModelModule } = await import('../../../phase-dependency-model/composition-root.js');
+      const { createPhaseDependencyModelModule } = await import("../../../phase-dependency-model/composition-root.js");
       const mod = createPhaseDependencyModelModule({
         rootDir: process.cwd(),
         phaseConfig: toPhaseConfigSection(resolvedConfig.config),
@@ -42,10 +63,10 @@ export class PhaseDependencyPhaseGatePolicyAdapter implements PhaseGatePolicyPor
           satisfied: false,
           violations: [
             {
-              code: { value: 'L2-001', toString: () => 'L2-001' },
-              severity: { value: 'error', toString: () => 'error' },
+              code: { value: "L2-001", toString: () => "L2-001" },
+              severity: { value: "error", toString: () => "error" },
               message: result.text,
-              suggestion: 'phase gate prerequisites are not met',
+              suggestion: buildPhaseGateRecoverySuggestion(context.unitName),
             },
           ],
         };
@@ -57,10 +78,10 @@ export class PhaseDependencyPhaseGatePolicyAdapter implements PhaseGatePolicyPor
         satisfied: false,
         violations: [
           {
-            code: { value: 'L2-002', toString: () => 'L2-002' },
-            severity: { value: 'error', toString: () => 'error' },
+            code: { value: "L2-002", toString: () => "L2-002" },
+            severity: { value: "error", toString: () => "error" },
             message: `phase gate check returned unexpected exit code ${result.exitCode}; prerequisites cannot be confirmed`,
-            suggestion: 'phase gate prerequisites could not be evaluated; treating as NOT satisfied (fail-closed)',
+            suggestion: "phase gate prerequisites could not be evaluated; treating as NOT satisfied (fail-closed)",
           },
         ],
       };
@@ -73,10 +94,10 @@ export class PhaseDependencyPhaseGatePolicyAdapter implements PhaseGatePolicyPor
         satisfied: false,
         violations: [
           {
-            code: { value: 'L2-002', toString: () => 'L2-002' },
-            severity: { value: 'error', toString: () => 'error' },
+            code: { value: "L2-002", toString: () => "L2-002" },
+            severity: { value: "error", toString: () => "error" },
             message: `phase gate prerequisite check could not be evaluated: ${message}`,
-            suggestion: 'phase gate prerequisites could not be evaluated; treating as NOT satisfied (fail-closed)',
+            suggestion: "phase gate prerequisites could not be evaluated; treating as NOT satisfied (fail-closed)",
           },
         ],
       };

package/scripts/harness/validator-system/infrastructure/adapters/traceability-metadata-policy-adapter.ts

@@ -4,8 +4,8 @@
  *
  * TraceabilityMetadataPolicyAdapter — MetadataPolicyPort実装
  */
-import type { MetadataPolicyPort } from '../../domain/ports/metadata-policy-port.js';
-import type { HarnessErrorLike } from '../../domain/value-objects/validation-result.js';
+import type { MetadataPolicyPort } from "../../domain/ports/metadata-policy-port.js";
+import type { HarnessErrorLike } from "../../domain/value-objects/validation-result.js";
 
 export class TraceabilityMetadataPolicyAdapter implements MetadataPolicyPort {
   async validateMetadata(context: { filePath: string; fileContent: string }): Promise<{
@@ -19,21 +19,26 @@ export class TraceabilityMetadataPolicyAdapter implements MetadataPolicyPort {
     const hasLayer = /@layer\s+\S+/.test(fileContent);
     const hasStoryId = /@story-id\s+H\d{2}-\d{2}/.test(fileContent) || /@story\s+H\d{2}-\d{2}/.test(fileContent);
 
+    // WI-335: この suggestion は「<directive> <値> を先頭コメントに追加」という機械適用可能な
+    // 文言契約を持つ（remediationType: 'mechanical'）。文言をこの形から変える場合は
+    // remediation-round-trip テスト（機械適用器が同じ文言を解析する）が fail する。
     if (!hasUnit) {
       errors.push({
-        code: { value: 'L2-002', toString: () => 'L2-002' },
-        severity: { value: 'error', toString: () => 'error' },
+        code: { value: "L2-002", toString: () => "L2-002" },
+        severity: { value: "error", toString: () => "error" },
         message: `メタデータ不足: @unit アノテーションがありません (${filePath})`,
-        suggestion: '// @unit <unit-name> を先頭コメントに追加してください',
+        suggestion: "// @unit <unit-name> を先頭コメントに追加してください",
+        remediationType: "mechanical",
       });
     }
 
     if (!hasLayer) {
       errors.push({
-        code: { value: 'L2-002', toString: () => 'L2-002' },
-        severity: { value: 'error', toString: () => 'error' },
+        code: { value: "L2-002", toString: () => "L2-002" },
+        severity: { value: "error", toString: () => "error" },
         message: `メタデータ不足: @layer アノテーションがありません (${filePath})`,
-        suggestion: '// @layer domain|application|infrastructure|presentation を先頭コメントに追加してください',
+        suggestion: "// @layer domain|application|infrastructure|presentation を先頭コメントに追加してください",
+        remediationType: "mechanical",
       });
     }
 

package/scripts/harness/validator-system/presentation/formatters/agent-validation-result-formatter.ts

@@ -4,34 +4,43 @@
  *
  * AgentValidationResultFormatter — AIエージェント向け詳細テキスト
  */
-import type { AggregatedValidationReport } from '../../application/dto/aggregated-validation-report.js';
+import type { AggregatedValidationReport } from "../../application/dto/aggregated-validation-report.js";
 
 export class AgentValidationResultFormatter {
   format(report: AggregatedValidationReport): string {
     const lines: string[] = [];
-    lines.push('VALIDATION_REPORT');
-    lines.push(`OVERALL: ${report.overallPassed ? 'PASS' : 'FAIL'}`);
-    lines.push(`TOTAL: ${report.totalValidators} PASSED: ${report.passedValidators} FAILED: ${report.failedValidators} SKIPPED: ${report.skippedValidators}`);
-    lines.push('');
+    lines.push("VALIDATION_REPORT");
+    lines.push(`OVERALL: ${report.overallPassed ? "PASS" : "FAIL"}`);
+    lines.push(
+      `TOTAL: ${report.totalValidators} PASSED: ${report.passedValidators} FAILED: ${report.failedValidators} SKIPPED: ${report.skippedValidators}`,
+    );
+    lines.push("");
 
     for (const result of report.results) {
       lines.push(`VALIDATOR: ${result.validatorId}`);
-      lines.push(`STATUS: ${result.skipped ? 'SKIPPED' : result.passed ? 'PASSED' : 'FAILED'}`);
+      lines.push(`STATUS: ${result.skipped ? "SKIPPED" : result.passed ? "PASSED" : "FAILED"}`);
       lines.push(`DURATION: ${result.durationMs}ms`);
       if (result.skipped && result.skipReason) {
         lines.push(`SKIP_REASON: ${result.skipReason}`);
       }
       if (result.errors.length > 0) {
-        lines.push('ERRORS:');
+        lines.push("ERRORS:");
         for (const error of result.errors) {
           lines.push(`  - CODE: ${error.code}`);
           lines.push(`    MESSAGE: ${error.message}`);
-          lines.push(`    SUGGESTION: ${error.suggestion}`);
+          // WI-357: 復旧手順を載せた suggestion は複数行になりうる。
+          // 素朴に埋め込むと 2 行目以降がインデントを失い、ERRORS ブロックの
+          // 構造が壊れて機械読みできなくなるため継続行を明示的に字下げする。
+          const suggestionLines = String(error.suggestion).split("\n");
+          lines.push(`    SUGGESTION: ${suggestionLines[0]}`);
+          for (const continuation of suggestionLines.slice(1)) {
+            lines.push(`      ${continuation}`);
+          }
         }
       }
-      lines.push('');
+      lines.push("");
     }
 
-    return lines.join('\n');
+    return lines.join("\n");
   }
 }

package/skills/product-architect/SKILL.md

@@ -35,6 +35,18 @@ languages: [typescript]
 ### 出力ファイル
 `docs/inception/_shared/product_overview_plan.md`
 
+> **テンプレート実体の取得（正本）**: 下の構成ブロックは読み取り用の要約であり、
+> 実体は `templates/product_overview_plan.template.md` にある。
+> node_modules を Read せずに取得・生成するには次を使う:
+>
+> ```bash
+> phasegate templates show product_overview_plan          # 本文を stdout に出力
+> phasegate scaffold-inception --kind product-overview-plan --apply  # 実ファイルを生成
+> ```
+>
+> scaffold した文書は無編集で Level-1 フェーズゲート（`interactive` モード）を通る。
+> `[Answer]` は **人間が記入する**。AI が埋めると承認証跡の偽造になる。
+
 ### 計画ファイルの構成
 
 ```markdown
@@ -93,6 +105,13 @@ languages: [typescript]
 |------|--------|
 | 成果物 | `docs/product/product_overview.md` |
 
+> **テンプレート実体の取得（正本）**: 実体は `templates/product_overview.template.md` にある。
+>
+> ```bash
+> phasegate templates show product_overview
+> phasegate scaffold-inception --kind product-overview --apply
+> ```
+
 ### product_overview.md の構成
 
 ```markdown

package/skills/quick-implementor/SKILL.md

@@ -21,6 +21,25 @@ Quick Mode下での軽微変更実装スキル。story-implementorの緩和版
 | `test` | テスト追加・修正（新機能のテストではない） |
 | `config` | 設定変更、依存バージョン更新 |
 
+> **カテゴリ判定はファイルパスベース（意図ベースではない）**
+> pre-tool-use hook は変更の「意図」ではなく **書き込み対象パス** からカテゴリを機械判定する。
+> 特に `config` は allowlist で、以下だけが `config` に落ちる:
+> `*.config.json` / `*.config.ts` / `phasegate.config.json` / `.github/workflows/*.y(a)ml` /
+> リポジトリ直下の `.gitignore` `.gitattributes` `.editorconfig` `.npmrc` `.nvmrc` `tsconfig.json` `tsconfig.*.json` / `.husky/` 配下。
+> allowlist 外のパスは新規作成（CREATE）なら `feature` に落ちて **必ずブロックされる**（fail-closed）。
+>
+> ブロックされたら、まず分類を確認する:
+> ```bash
+> npx phasegate check-change-category --paths <file1>,<file2>
+> ```
+> 判定が妥当で、かつ許可カテゴリの一時拡張が必要なら CLI 経由で計画・適用する
+> （`phasegate.config.json` の手編集は保護ファイルとしてブロックされる）:
+> ```bash
+> npx phasegate config:plan --intent quick-mode-relax --dry-run --json   # 差分確認
+> npx phasegate config:plan --intent quick-mode-relax --apply --json     # 承認後に適用
+> ```
+> 判定が `feature` / `domain` / `api` なら、それは Quick Mode のスコープ外。`story-implementor` に切り替える。
+
 ### WI-aware trivial path（ISSUE-026 Phase D）
 
 作業対象に `WI-XXX` が明示されている場合、最初に `docs/inception/{unit}/WI-XXX/description.md` または `docs/inception/_cross/WI-XXX/description.md` のfrontmatterを確認する。

package/skills/story-mapper/SKILL.md

@@ -81,6 +81,17 @@ MVPスコープの方針・分類基準・不明点を整理し、人間の承
 ### 出力ファイル
 `docs/inception/_shared/story_mapping_plan.md`
 
+> **テンプレート実体の取得（正本）**: 下の構成ブロックは読み取り用の要約であり、
+> 実体は `templates/story_mapping_plan.template.md` にある。
+> node_modules を Read せずに取得・生成するには次を使う:
+>
+> ```bash
+> phasegate templates show story_mapping_plan
+> phasegate scaffold-inception --kind story-mapping-plan --apply
+> ```
+>
+> `[Answer]` は **人間が記入する**。AI が埋めると承認証跡の偽造になる。
+
 ### 計画ファイルの構成
 
 ```markdown

package/skills/story-writer/SKILL.md

@@ -45,6 +45,17 @@ If not, halt and ask the user to create the WI first, or offer to run `phasegate
 ### 出力ファイル
 `docs/inception/_shared/story_writer_plan.md`
 
+> **テンプレート実体の取得（正本）**: 下の構成ブロックは読み取り用の要約であり、
+> 実体は `templates/story_writer_plan.template.md` にある。
+> node_modules を Read せずに取得・生成するには次を使う:
+>
+> ```bash
+> phasegate templates show story_writer_plan
+> phasegate scaffold-inception --kind story-writer-plan --apply
+> ```
+>
+> `[Answer]` は **人間が記入する**。AI が埋めると承認証跡の偽造になる。
+
 ### 計画ファイルの構成
 
 ```markdown

package/skills/unit-designer/SKILL.md

@@ -84,6 +84,17 @@ Unit分割の方針・グルーピングの根拠・不明点を整理し、人
 
 > **パス注記**: 本スキルが扱う設計文書パス（`docs/inception/...` / `docs/product/units/...`）は既定値であり、consumer が `phasegate.config.json` の `paths` 設定で上書きしている場合はそちらが優先される。
 
+> **テンプレート実体の取得（正本）**: 下の構成ブロックは読み取り用の要約であり、
+> 実体は `templates/unit_design_plan.template.md` にある。
+> node_modules を Read せずに取得・生成するには次を使う:
+>
+> ```bash
+> phasegate templates show unit_design_plan
+> phasegate scaffold-inception --kind unit-design-plan --apply
+> ```
+>
+> `[Answer]` は **人間が記入する**。AI が埋めると承認証跡の偽造になる。
+
 ### 計画ファイルの構成
 
 ```markdown

package/templates/product_overview.template.md

@@ -0,0 +1,85 @@
+# <プロダクト名>
+
+> **スキル**: `product-architect` Phase 2（実行）
+> **入力**: `docs/inception/_shared/product_overview_plan.md`（承認済み）
+> **作成日**: <YYYY-MM-DD>
+
+このファイルは `phasegate scaffold-inception --kind product-overview --apply`
+が生成した雛形です。TODO を実体で埋めてください。
+このドキュメントは全スキルの**前提**として参照されます。
+
+---
+
+## 1. プロダクト定義
+
+### 1.1 根本思想
+
+TODO: このプロダクトが何を信条として作られるかを 2〜3 行で記述
+
+### 1.2 解決する問題
+
+TODO: 現状の痛みと、それが放置された場合のコスト
+
+### 1.3 対象ユーザー
+
+TODO: 主ターゲットと、明示的に対象外とするユーザー
+
+## 2. コアドメイン
+
+### 2.1 主要概念（ユビキタス言語）
+
+| 概念 | 定義 | 例 |
+|------|------|-----|
+| TODO | TODO | TODO |
+
+### 2.2 概念間の関係図
+
+```mermaid
+graph TD
+  A[TODO] --> B[TODO]
+```
+
+## 3. アーキテクチャ仕様
+
+### 3.1 全体構造（レイヤー図）
+
+```
+TODO: レイヤー構成
+```
+
+### 3.2 技術スタック
+
+| レイヤー | 技術 | 選定理由 |
+|---------|------|---------|
+| TODO | TODO | TODO |
+
+### 3.3 分離方針
+
+TODO: 認証/認可、同期/非同期 等の分離方針
+
+## 4. ADR Summary（技術決定記録）
+
+| # | 決定事項 | 選択肢 | 決定 | 理由 |
+|---|---------|-------|------|------|
+| 1 | TODO | TODO | TODO | TODO |
+
+## 5. 制約
+
+### 5.1 運用上の制約
+
+TODO
+
+### 5.2 実装上の制約
+
+TODO
+
+### 5.3 パフォーマンス要件
+
+TODO
+
+---
+
+## 注意事項
+
+- ユビキタス言語はプロジェクト全体で一貫して使用する
+- 技術選定の「なぜ」を必ず ADR Summary に記録する

package/templates/product_overview_plan.template.md

@@ -0,0 +1,55 @@
+# プロダクト設計計画
+
+> **スキル**: `product-architect` Phase 1（計画）
+> **成果物**: `docs/product/product_overview.md`（Phase 2 で作成）
+> **作成日**: <YYYY-MM-DD>
+
+このファイルは `phasegate scaffold-inception --kind product-overview-plan --apply`
+が生成した雛形です。TODO を実体で埋めてください。
+**QA セクションの `[Answer]` は人間が記入するもので、AI が埋めてはいけません。**
+
+---
+
+## 1. スコープ
+
+- TODO: プロダクトの目的と対象ユーザー概要
+- TODO: 設計対象セクション一覧
+
+## 2. ドメイン分析（ドラフト）
+
+- TODO: 特定されたコアドメイン
+- TODO: 主要業務概念の候補一覧（ユビキタス言語の種）
+
+## 3. アーキテクチャ方針（ドラフト）
+
+- TODO: 想定されるアーキテクチャスタイル
+- TODO: 技術スタック候補
+
+## 4. QA（不明点・確認事項）
+
+### [Question] Q1: <質問タイトル>
+
+<質問の詳細と背景>
+
+**推奨案:** <AI の推奨案>
+
+> 下の `[Answer]` 行の直後に **人間が** 回答を記入してください。
+> 空欄のままだと `planningMode: "embedded-qa"` のフェーズゲートは通りません（意図した挙動です）。
+
+[Answer]
+
+## 5. 前提条件・リスク
+
+- TODO: 前提条件
+- TODO: リスクと対応方針
+
+---
+
+## フェーズゲートとの関係
+
+- `planningMode.default: "interactive"`（既定）では、`## 4. QA（不明点・確認事項）`
+  という **QA セクション見出しの存在** が Level-1 ゲート通過条件です。
+  見出しは `## QA` / `## Q&A` / `## 4. QA（...）` のいずれの表記でも構いません。
+- `planningMode.default: "embedded-qa"` では、`[Question]` と `[Answer]` の
+  **個数一致かつ [Answer] に本文があること** が追加で要求されます。
+  この雛形のままではゲートを通りません（人間の回答が必要）。これは意図した挙動です。