phasegate 0.340.0 → 0.341.0

package/scripts/harness/skill-quality/application/usecases/execute-tdd-cycle-usecase.ts

@@ -13,7 +13,8 @@ export class ExecuteTddCycleUseCase {
 
   async execute(input: ExecuteTddCycleInput): Promise<ExecuteTddCycleOutput> {
     const tddCycle = TddCycle.create(input.phase, input.passed);
-    const commitMessage = CommitMessage.create(input.unit, input.storyId, input.description);
+    const workItemId = /^WI-\d+$/.test(input.storyId) ? input.storyId : undefined;
+    const commitMessage = CommitMessage.create(input.unit, input.storyId, input.description, workItemId);
 
     const readiness = await this.atomicCommitService.execute(tddCycle, commitMessage);
 

package/scripts/harness/skill-quality/application/usecases/run-plan-checker-loop-usecase.ts

@@ -26,6 +26,14 @@ export class RunPlanCheckerLoopUseCase {
         revision: result.revision,
       });
       loop.addAttempt(attempt);
+      if (loop.status === 'RUNNING' && this.planCheckExecutorPort.supportsRetry === false) {
+        return {
+          status: 'FAILED_EXCEEDED',
+          loopHistory: loop.loopHistory,
+          escalationRequired: true,
+          stopReason: 'UNCHANGED_INPUT',
+        };
+      }
       attemptNumber++;
     }
 

package/scripts/harness/skill-quality/composition-root.ts

@@ -14,7 +14,7 @@ import { SkillStructureValidator } from './domain/services/skill-structure-valid
 
 // Infrastructure Adapters
 import { GitCommitExecutorAdapter } from './infrastructure/adapters/git-commit-executor-adapter.js';
-import { L1BiomeValidatorAdapter } from './infrastructure/adapters/l1-biome-validator-adapter.js';
+import { L1BiomeValidatorAdapter, type L1BiomeValidatorOptions } from './infrastructure/adapters/l1-biome-validator-adapter.js';
 import { L2ValidatorSystemAdapter } from './infrastructure/adapters/l2-validator-system-adapter.js';
 import { FileSystemLessonSourceReaderAdapter } from './infrastructure/adapters/file-system-lesson-source-reader-adapter.js';
 import { FileSystemLessonArtifactWriterAdapter } from './infrastructure/adapters/file-system-lesson-artifact-writer-adapter.js';
@@ -60,11 +60,18 @@ class NodeFileSystemAdapter implements FileSystemPort {
   }
 }
 
-export function createSkillQualityHandlers() {
+export interface SkillQualityHandlerOptions {
+  rootDir?: string;
+  l1Config?: L1BiomeValidatorOptions['config'];
+  validatorSystemConfig?: object;
+  failOnWarning?: boolean;
+}
+
+export function createSkillQualityHandlers(options: SkillQualityHandlerOptions = {}) {
   // Infrastructure
   const commitExecutorPort = new GitCommitExecutorAdapter();
-  const l1ValidatorPort = new L1BiomeValidatorAdapter();
-  const l2ValidatorPort = new L2ValidatorSystemAdapter();
+  const l1ValidatorPort = new L1BiomeValidatorAdapter({ rootDir: options.rootDir, config: options.l1Config });
+  const l2ValidatorPort = new L2ValidatorSystemAdapter({ config: options.validatorSystemConfig, failOnWarning: options.failOnWarning });
   const lessonSourceReaderPort = new FileSystemLessonSourceReaderAdapter();
   const lessonArtifactWriterPort = new FileSystemLessonArtifactWriterAdapter();
   const lessonArtifactSchemaPort = new AjvLessonArtifactSchemaAdapter();
@@ -87,6 +94,7 @@ export function createSkillQualityHandlers() {
   const checkCoverageUseCase = new CheckCoverageUseCase(requirementTestMatrixPort, coverageRunnerPort, configQueryPort);
   const runPlanCheckerLoopUseCase = new RunPlanCheckerLoopUseCase(
     {
+      supportsRetry: false,
       evaluate: async (planDocument: string) => {
         // チェックボックス形式（- [x] / - [ ]）でカバレッジを評価する
         const checked = (planDocument.match(/- \[x\]/gi) ?? []).length;
@@ -99,8 +107,7 @@ export function createSkillQualityHandlers() {
         const gaps = planDocument
           .split('\n')
           .filter((line) => /- \[ \]/.test(line))
-          .map((line) => line.replace(/^.*- \[ \]\s*/, '').trim())
-          .filter(Boolean);
+          .map((line) => line.replace(/^.*- \[ \]\s*/, '').trim() || '未記入のチェック項目');
         return { coverageRate, gaps, revision: `${checked}/${total}` };
       },
     }
@@ -114,7 +121,7 @@ export function createSkillQualityHandlers() {
   return {
     executeTddCycleHandler: new ExecuteTddCycleHandler(executeTddCycleUseCase),
     checkCoverageHandler: new CheckCoverageHandler(checkCoverageUseCase),
-    runPlanCheckerLoopHandler: new RunPlanCheckerLoopHandler(runPlanCheckerLoopUseCase),
+    runPlanCheckerLoopHandler: new RunPlanCheckerLoopHandler(runPlanCheckerLoopUseCase, fileSystemPort),
     collectLessonsHandler: new CollectLessonsHandler(collectLessonsUseCase, writeLessonArtifactUseCase),
     applyCascadeUpdateHandler: new ApplyCascadeUpdateHandler(applyCascadeUpdateUseCase),
     validateSkillStructureHandler: new ValidateSkillStructureHandler(validateSkillStructureUseCase),

package/scripts/harness/skill-quality/domain/ports/plan-check-executor-port.ts

@@ -11,5 +11,7 @@ export interface PlanCheckResult {
 }
 
 export interface PlanCheckExecutorPort {
+  /** False for deterministic evaluators; omitted preserves legacy retry behavior. */
+  readonly supportsRetry?: boolean;
   evaluate(planDocument: string, previousAttempts: readonly LoopAttempt[]): Promise<PlanCheckResult>;
 }

package/scripts/harness/skill-quality/domain/value-objects/cascade-update-target.ts

@@ -1,6 +1,7 @@
 /**
  * @layer domain
  * @unit skill-quality
+ * @work-item-id WI-220
  */
 import { SkillQualityError } from '../errors/skill-quality-error.js';
 
@@ -18,11 +19,24 @@ export class CascadeUpdateTarget {
     if (!filePath) {
       throw new SkillQualityError('EMPTY_FILE_PATH', 'filePath must be non-empty');
     }
-    const storyIdTag = `@story-id ${storyId}`;
+    const storyIdTag = `@${/^WI-\d+$/.test(storyId) ? 'work-item-id' : 'story-id'} ${storyId}`;
     return new CascadeUpdateTarget(filePath, storyIdTag);
   }
 
   equals(other: CascadeUpdateTarget): boolean {
     return this.filePath === other.filePath && this.storyIdTag === other.storyIdTag;
   }
+
+  renderAnnotation(filePath: string): string {
+    return /\.(?:[cm]?[jt]s|[jt]sx)$/i.test(filePath) ? `// ${this.storyIdTag}` : this.storyIdTag;
+  }
+
+  hasAnnotationIn(content: string): boolean {
+    const storyId = this.storyIdTag.slice(this.storyIdTag.indexOf(' ') + 1);
+    for (const match of content.matchAll(/@(?:story-id|issue-id|work-item-id)[ \t]+([^\r\n]+)/g)) {
+      const ids = match[1].replace(/-->.*$/, '').split(/[\s,]+/);
+      if (ids.includes(storyId)) return true;
+    }
+    return false;
+  }
 }

package/scripts/harness/skill-quality/infrastructure/adapters/l1-biome-validator-adapter.ts

@@ -5,12 +5,20 @@
 import type { L1ValidatorPort } from '../../domain/ports/l1-validator-port.js';
 import type { CommitMessage } from '../../domain/value-objects/commit-message.js';
 import type { ValidationViolation } from '../../domain/types/validation-violation.js';
+import type { BiomeAstEngineModuleOptions } from '../../../biome-ast-engine/composition-root.js';
+
+export interface L1BiomeValidatorOptions {
+  rootDir?: string;
+  config?: BiomeAstEngineModuleOptions;
+}
 
 export class L1BiomeValidatorAdapter implements L1ValidatorPort {
+  constructor(private readonly options: L1BiomeValidatorOptions = {}) {}
+
   async validate(_commitMessage: CommitMessage): Promise<readonly ValidationViolation[]> {
     try {
       const { createBiomeAstEngineModule } = await import('../../../biome-ast-engine/composition-root.js');
-      const mod = createBiomeAstEngineModule(process.cwd());
+      const mod = createBiomeAstEngineModule(this.options.rootDir ?? process.cwd(), this.options.config);
       const output = await mod.executeLintUseCase.execute({ targets: [] });
 
       return output.report.violations.map((violation) => ({

package/scripts/harness/skill-quality/infrastructure/adapters/l2-validator-system-adapter.ts

@@ -5,20 +5,36 @@
 import type { L2ValidatorPort } from '../../domain/ports/l2-validator-port.js';
 import type { CommitMessage } from '../../domain/value-objects/commit-message.js';
 import type { ValidationViolation } from '../../domain/types/validation-violation.js';
+import { isEffectivelyPassed } from '../../../validator-system/domain/services/effective-severity-policy.js';
+
+export interface L2ValidatorSystemOptions {
+  config?: object;
+  failOnWarning?: boolean;
+}
 
 export class L2ValidatorSystemAdapter implements L2ValidatorPort {
+  constructor(private readonly options: L2ValidatorSystemOptions = {}) {}
+
   async validate(_commitMessage: CommitMessage): Promise<readonly ValidationViolation[]> {
     try {
       const { createValidatorSystemModule } = await import('../../../validator-system/composition-root.js');
-      const mod = createValidatorSystemModule();
+      const mod = createValidatorSystemModule(this.options.config);
+      // Direct legacy callers keep warning-as-blocking unless explicitly configured.
+      const failOnWarning = this.options.failOnWarning ?? true;
       const report = await mod.runFullValidationUseCase.execute({
         targetPaths: [],
         unitName: '',
         currentPhase: '',
         includeL4: false,
+        failOnWarning,
       });
 
-      return report.allErrors.map((error) => ({
+      const blockingErrors = report.allErrors.filter((error) => {
+        const advisory = isEffectivelyPassed({ passed: false, errors: [error] }, failOnWarning);
+        if (advisory) console.warn(`[skill-quality] [${error.code}] ${error.message}`);
+        return !advisory;
+      });
+      return blockingErrors.map((error) => ({
         ruleId: error.code.toString(),
         message: error.message,
         location: '',

package/scripts/harness/skill-quality/presentation/handlers/apply-cascade-update-handler.ts

@@ -2,6 +2,7 @@
  * @layer presentation
  * @unit skill-quality
  * @work-item-id WI-192
+ * @work-item-id WI-220
  */
 import type { ApplyCascadeUpdateUseCase } from '../../application/usecases/apply-cascade-update-usecase.js';
 
@@ -20,12 +21,17 @@ export class ApplyCascadeUpdateHandler {
       if (args.format === 'json') {
         return {
           exitCode: output.errors.length > 0 ? 1 : 0,
-          message: JSON.stringify({ dryRun: args.dryRun === true, ...output }, null, 2),
+          message: JSON.stringify({
+            dryRun: args.dryRun === true,
+            ...output,
+            operation: 'traceability-tag-update',
+            semanticReviewPerformed: false,
+          }, null, 2),
         };
       }
       const tagsLine = output.appliedStoryIds.join(', ');
       const verb = args.dryRun ? 'Would update' : 'Updated';
-      let msg = `${verb} ${output.updatedCount} files with tags: ${tagsLine}`;
+      let msg = `${verb} ${output.updatedCount} files with tags: ${tagsLine}\nタグ追記のみです。意味レビューは未実施であり、設計内容の反映・承認を保証しません。`;
 
       if (output.errors.length > 0) {
         const errLines = output.errors.map((e) => `  - ${e}`).join('\n');

package/scripts/harness/skill-quality/presentation/handlers/execute-tdd-cycle-handler.ts

@@ -16,6 +16,7 @@ export class ExecuteTddCycleHandler {
   constructor(private readonly useCase: ExecuteTddCycleUseCase) {}
 
   async handle(args: ExecuteTddCycleArgs): Promise<{ exitCode: number; message: string }> {
+    const evidenceNotice = '\n注意: --passed は呼出元の申告です。このコマンドはテストを実行しません。';
     try {
       const output = await this.useCase.execute({
         unit: args.unit,
@@ -26,12 +27,12 @@ export class ExecuteTddCycleHandler {
       });
 
       if (output.ready) {
-        return { exitCode: 0, message: `Commit successful: ${output.committedMessage}` };
+        return { exitCode: 0, message: `Commit successful: ${output.committedMessage}${evidenceNotice}` };
       }
       const violationMessages = output.violations.map((v) => `  - [${v.ruleId}] ${v.message}`).join('\n');
-      return { exitCode: 1, message: `Validation failed:\n${violationMessages}` };
+      return { exitCode: 1, message: `Validation failed:\n${violationMessages}${evidenceNotice}` };
     } catch (err) {
-      return { exitCode: 2, message: `Error: ${err instanceof Error ? err.message : String(err)}` };
+      return { exitCode: 2, message: `Error: ${err instanceof Error ? err.message : String(err)}${evidenceNotice}` };
     }
   }
 }

package/scripts/harness/skill-quality/presentation/handlers/run-plan-checker-loop-handler.ts

@@ -3,6 +3,7 @@
  * @unit skill-quality
  */
 import type { RunPlanCheckerLoopUseCase } from '../../application/usecases/run-plan-checker-loop-usecase.js';
+import type { FileSystemPort } from '../../domain/ports/file-system-port.js';
 
 export interface RunPlanCheckerLoopArgs {
   planFile: string;
@@ -10,12 +11,15 @@ export interface RunPlanCheckerLoopArgs {
 }
 
 export class RunPlanCheckerLoopHandler {
-  constructor(private readonly useCase: RunPlanCheckerLoopUseCase) {}
+  constructor(
+    private readonly useCase: RunPlanCheckerLoopUseCase,
+    private readonly planReader?: Pick<FileSystemPort, 'read'>,
+  ) {}
 
   async handle(args: RunPlanCheckerLoopArgs): Promise<{ exitCode: number; message: string }> {
     try {
       const output = await this.useCase.execute({
-        planDocument: args.planFile,
+        planDocument: this.planReader ? await this.planReader.read(args.planFile) : args.planFile,
         storyId: args.storyId,
       });
 
@@ -24,9 +28,12 @@ export class RunPlanCheckerLoopHandler {
       ).join('\n');
 
       if (output.escalationRequired) {
-        return { exitCode: 1, message: `Plan check FAILED_EXCEEDED - escalation required\n${historyLines}` };
+        const guidance = output.stopReason === 'UNCHANGED_INPUT'
+          ? '\n同じ入力の再試行では改善しません。文書を修正するか判断を求めてください。'
+          : '';
+        return { exitCode: 1, message: `Plan check FAILED_EXCEEDED - escalation required\n${historyLines}${guidance}\nこの結果は設計の意味的承認ではありません。` };
       }
-      return { exitCode: 0, message: `Plan check PASSED\n${historyLines}` };
+      return { exitCode: 0, message: `Plan check PASSED\n${historyLines}\nこの結果は設計の意味的承認ではありません。` };
     } catch (err) {
       return { exitCode: 2, message: `Error: ${err instanceof Error ? err.message : String(err)}` };
     }

package/scripts/harness/traceability-model/infrastructure/parsers/work-item-frontmatter-parser.ts

@@ -31,6 +31,47 @@ const flowArrayPattern = (key: string): RegExp => new RegExp(`^\\s*${key}\\s*:\\
 const blockArrayPattern = (key: string): RegExp =>
   new RegExp(`^\\s*${key}\\s*:\\s*\\r?\\n((?:[ \\t]+-[ \\t]+.+\\r?\\n?)+)`, "m");
 
+/** Opt-in dependency diagnostics; existing metadata readers keep their old contract. */
+export function parseWorkItemDependencies(content: string): readonly string[] | undefined {
+  const body = FRONTMATTER_PATTERN.exec(content)?.[1];
+  if (body === undefined) return undefined;
+  const lines = body.split(/\r?\n/);
+  const headers = lines.flatMap((line, index) => /^[ \t]*depends_on[ \t]*:/.test(line) ? [index] : []);
+  if (headers.length === 0) return undefined;
+  const invalid = (reason: string): never => {
+    throw new WorkItemFrontmatterValidationError(`depends_on ${reason}`);
+  };
+  if (headers.length !== 1) return invalid('が重複しています');
+  if (!lines[headers[0]].startsWith('depends_on')) return invalid('はfrontmatter直下に指定してください');
+  const withoutComment = (value: string) => value.replace(/[ \t]+#.*$/, '').trim();
+  const declaration = withoutComment(lines[headers[0]].replace(/^[ \t]*depends_on[ \t]*:/, ''));
+  const continuation: string[] = [];
+  for (const line of lines.slice(headers[0] + 1)) {
+    if (line.trim() === '' || line.trimStart().startsWith('#')) continue;
+    if (/^[^\s:#][^:]*:/.test(line)) break;
+    continuation.push(line);
+  }
+  let values: string[];
+  if (declaration.startsWith('[') && declaration.endsWith(']')) {
+    if (continuation.length > 0) return invalid('のflow配列に続く行が不正です');
+    const inner = declaration.slice(1, -1).trim();
+    values = inner === '' ? [] : inner.split(',');
+  } else if (declaration === '') {
+    values = [];
+    for (const line of continuation) {
+      const item = /^[ \t]+-[ \t]+(.+)$/.exec(line);
+      if (!item) return invalid('はWI IDの配列で指定してください');
+      values.push(withoutComment(item[1]));
+    }
+    if (values.length === 0) return invalid('の空宣言には [] を指定してください');
+  } else {
+    return invalid('はWI IDの配列で指定してください');
+  }
+  const ids = values.map((value) => stripYamlQuotes(value.trim()));
+  if (ids.some((id) => !/^WI-\d+$/.test(id))) return invalid('に不正なWI IDまたは空項目があります');
+  return Object.freeze(ids);
+}
+
 export function parseWorkItemFrontmatter(content: string): WorkItemFrontmatter | null {
   const match = FRONTMATTER_PATTERN.exec(content);
   if (!match) return null;

package/skills/README.md

@@ -20,4 +20,11 @@
 
 ## 新しいスキルの追加
 
+### 利用者向けの選択
+
+<!-- @work-item-id WI-223 -->
+`phasegate install --skills consumer --dry-run`で本体メンテナー用の`release-publisher`と`skill-creator`を除く27件を確認できる。適用は`--apply`を明示する。既存の`core`は7件、`all`と省略時は29件のまま。reconcileは各配置先の`.harness-version`に記録したセットを維持する。セット変更だけで以前のスキルやユーザー作成スキルを削除しないため、既存allからの切替は削除移行ではない。
+
+配布カタログの正本は`installation/application/bundled-skill-selection.ts`の一箇所。consumerは言語非依存化済みという意味ではなく、Vitest/Playwright等の技術固有スキルは引き続き含まれる。
+
 新しいスキルを追加する場合は、この `skills` ディレクトリに直接追加してください。あわせて `docs/guide/skills-overview.md`、README の skill 数、必要なら `skills/phasegate-toolkit-guide/SKILL.md` の参照先を更新します。シンボリックリンクを通じて、対応エージェントから利用可能になります。<!-- @work-item-id WI-154 -->

package/skills/cascade-updater/SKILL.md

@@ -1,141 +1,69 @@
 ---
 name: cascade-updater
-description: 下位フェーズの発見・変更を上位設計文書にフィードバックし影響範囲を整合的に更新
-model: sonnet
-review: opus
+description: WIの設計反映や下位の発見を起点に、上位判断が必要な変更を識別し、設計本文と下位成果物の整合を更新する。
 languages: [typescript]
 ---
 
 # Cascade Updater
 
-下位フェーズでの発見・変更・人間からの指示を、正しいレイヤーの設計文書にフィードバックし、影響範囲を整合的に更新するスキル。
+## 目的
 
-## storyReflection ゲート通過の標準手段
+上位の意図を成果物へ伝え、下位で見つかった前提の破綻を必要な上位判断へ戻す。ゲート通過のためのタグ追記だけで終えない。
 
-`phaseDependencies.storyReflection`（ADR-013）は、`docs/inception/{unit}/{storyId}/` 配下の US/issue 設計が `docs/product/construction/{unit}/` の累積設計文書に反映されていない場合、`src/{unit}/*`（phasegate 自リポジトリ（dogfood）では `scripts/harness/{unit}/*`）への Write/Edit（Bash 迂回経由の書き込みも含む）を pre-tool-use hook でブロックする。
+## 入力
 
-**cascade-updater はこの storyReflection ゲートを通過する標準手段である。**
+対象WI、発見・変更の内容と観測元、関連する設計・実装・テスト。既存の依頼とファイルから特定できる情報は再質問しない。意味や変更範囲が決まらない点だけ確認する。
 
-- `full` / `standard` プリセットでは、inception の新規 US/issue を作成した後、実装着手前に cascade-updater を実行して product 文書に `@story-id {storyId}` を追記する
-- cascade-updater を実行せずに実装へ進もうとすると `[L2-STORY-REFLECTION]` ブロックが発生する（エラー中で本スキルの実行が案内される）
-- `minimal` プリセットでは storyReflection が無効化されるためゲート連動しないが、cascade-updater による設計整合性の維持は推奨される
-- Quick Mode (`relaxedGates: ["phase-gate"]`) 時は storyReflection も緩和されるため、cascade-updater 実行の必須性は緩まる（ただし品質維持のため実行は推奨）
+## 前提条件
 
-詳細は ADR-013 および `docs/guide/configuration.md` の storyReflection セクションを参照（consumer プロジェクトでは `node_modules/phasegate/docs/ADR/...` / `node_modules/phasegate/docs/guide/...`、phasegate 自リポジトリでは `docs/...` を参照する）。
+プロジェクトのAGENTS.md、ドキュメント配置規則、対象WIと関連product設計を正本とする。配置rootはそのプロジェクトの設定を確認し、Phasegate自体のパスをconsumerへ強制しない。
 
-## 前提条件チェック
+- 標準配置では単一Unit WIは `docs/inception/{unit}/{WI-XXX}/`、横断WIは `docs/inception/_cross/{WI-XXX}/`。crossのaffectsと共有契約への実際の依存を確認する。
+- 既存の実行権限・保護設定・gateは維持する。このスキルの使用やタグの存在は書込みの認可にならない。
+- 実行モデルや委任可否はプロジェクトのモデルルーティングに従う。固定モデルへの委任や新たな承認段階を必須にしない。
+- 帰属が曖昧な場合だけ [層別判定ガイド](references/層別判定ガイド.md) を読む。ファイルの置き場所だけでリスクを決めない。
 
-### 必須インプット
-- **変更内容の記述** — 何が発見/変更されたか
-- **変更が発生したレイヤー** — どのフェーズで発見されたか
+## 実行フロー
 
----
-
-## ⚠️ 3フェーズ実行ルール
-
-**このスキルは3フェーズで実行する。**
-- **Phase 1（計画）**: Opus がスコープ・方針・不明点を整理し、人間の承認を得る
-- **Phase 2（実行）**: プロジェクトのモデルルーティング設定に従い、実行モデルに委譲して成果物を生成する
-- **Phase 3（レビュー）**: Opus が成果物を検証し、問題があれば直接修正する
-
-**Phase 1/2/3を同時に実行してはならない。**
-
----
-
-## Phase 1: 影響分析（plan）
-
-### 目的
-変更の帰属レイヤーを判定し、影響範囲を特定して人間の承認を得る。
+### 影響と判断を分ける
 
-### 出力
-会話内で以下を報告する（ファイルは作成しない）：
+現行設計、発見の根拠、対象revision（commitと必要な作業差分）を確認し、どの前提と下位成果物へ影響するかを対象WIに記録する。既存記録を更新し、並行する新台帳を作らない。
 
-```markdown
-# カスケード更新 影響分析
+- **合意済みの意味を変えない整合修正**：依頼された範囲なら追加の一律承認を待たずに進める。例：設計と実装の用語一致、重複説明の統合、契約を変えない内部抽出の設計反映。
+- **上位の判断を変える変更**：目的・受け入れ条件・公開API・認可・データ契約・業務不変条件・Unit境界、または依頼範囲の変更は決定者へ確認する。既に明示承認された判断を同じ内容で再度要求しない。
+- **判断不明**：影響する契約と不明点を示す。安全な調査や計画は続け、未確定の前提に依存する実装は保留する。未知を自動許可にも全作業停止にも変えない。
 
-## 1. 変更の起点
-- 発見元: {フェーズ/ストーリー}
-- 内容: {変更内容}
+上位判断が必要なときは、既存WI／必要なADRへ「観測・根拠」「変わる前提とrevision」「選択肢と影響」「決定者」「停止範囲」「再開条件」を残し、判断を求める。止めるのはその判断に依存する作業だけ。承認待ちを同じコマンドの自動再試行へ置き換えない。
 
-## 2. 帰属レイヤー判定
-- 判定結果: {環境設計 / 論理設計 / Domain / ストーリー}
-- 理由: {判定理由}
-参考: references/層別判定ガイド.md
+### 設計本文へ反映する
 
-## 3. 影響を受ける文書一覧
-| # | ファイル | 予定される変更内容 |
-|---|---------|-----------------|
+合意した最上位の設計から必要な下位設計、実装・テストへ伝える。実装はプロジェクトのフェーズ順序・必要なproduct反映を満たしてから行う。調査だけの依頼なら変更案までで止める。
 
-## 4. QA（不明点・確認事項）
+productは**現行仕様を一貫して読める本文**へ統合・置換する。旧説明と矛盾する追記を積み重ねない。意味を変える削除には上位判断が必要だが、合意済み意味を保つ重複・旧説明の整理まで一律承認にしない。理由・旧仕様との差・根拠はWI／ADR／Gitで追跡可能にする。
 
-### [Question] Q1: {質問タイトル}
-{質問の詳細と背景}
-**推奨案:** {AIの推奨案}
+新しいWI反映には `@work-item-id WI-XXX` を付ける。既存legacyタグと履歴参照は維持し、一括改番・置換しない。タグは参照の証拠であって、本文の意味的反映の証明ではない。
 
-[Answer]
-（人間が回答を記入）
-```
+### 判断後に再開・終了する
 
-### Phase 1 完了条件
-- 影響分析を報告した
-- 不明点がある場合は`[Question]`セクションに記載した
-- **人間にボールを渡した**
-- **設計文書はまだ更新していない**
-
----
+| 判断 | 次の行動 |
+|---|---|
+| 承認 | 決定と対象revisionを記録し、上位設計から依存成果物へ反映して再検証する。満たした再開条件で対象作業を再開する |
+| 却下 | その変更案を終了する。旧契約内で目的を達成できる場合は再計画し、同じ案の承認要求を繰り返さない |
+| 代替案 | 明示的に選ばれた案と範囲に合わせて再計画する。提示された選択肢を承認と推定しない |
+| 判断後に前提が変更 | 変更された前提と影響だけを再評価する。古い承認を新revisionへ無条件に流用しない |
 
-## Phase 2: 実行（execution）
+設計レビュー、機械検証、テスト結果を別々に記録する。World Modelを利用している場合は既存の明示依存／pinの両端のrevisionを確認し、その運用に従って必要なレビューを更新する。未導入環境に導入を要求せず、baseline／waiverを削除して解決したことにしない。
 
-### 開始条件
-- 人間がPhase 1の影響分析を承認した
+## 出力と完了条件
 
-### ワークフロー
-
-1. **該当レイヤーの文書を更新** — 変更内容を反映（追記優先、変更理由を記録）
-2. **下位レイヤーの影響確認** — 更新により下位文書に矛盾が生じないか確認・更新
-3. **更新レポート出力** — 変更した全文書の一覧と変更内容を報告
-
-### 更新時の原則
-
-- **更新は該当レイヤー以下のみ** — 上位の抽象設計は汚さない
-- **追記優先** — 既存の記述を削除するのではなく、新しい制約・ルールを追記する
-- **変更理由を記録** — なぜこの変更が必要になったかを文書内に簡潔に記録する
-
-### Phase 2 最低出力基準（Sonnet委任時の品質制約）
-
-以下の基準を満たさない出力は不完全とみなし、Phase 3レビューでBLOCKとする。
-
-| 基準 | 最低要件 |
-|------|---------|
-| 帰属レイヤー明記 | 各変更が帰属するレイヤーが明示されていること |
-| 変更理由記録 | 全変更箇所に変更理由が記録されていること |
-| 追記優先 | 既存記述の削除ではなく追記で対応していること（削除は明示的承認があった場合のみ） |
-| 下位影響確認 | 更新による下位文書への影響が確認・記録されていること |
-| 更新レポート | 変更した全文書の一覧と変更内容が報告されていること |
-
-詳細な判定パターンと具体例は [references/層別判定ガイド.md](references/層別判定ガイド.md) を参照。
-
----
+対象WIの記録から、変更理由・判断、対象revision、更新した上位／下位文書、関連実装・テストと検証結果へ到達できるようにする。無関係なWIの再審査はしない。
 
-## Phase 3: レビュー（Opus review）
+完了前に、現行productの矛盾が解消されたか、上位の決定が必要な下位成果物へ伝わったか、検証が更新後のrevisionを対象としているかを確認する。未実施テストや残る上位判断は未完了と明記する。下位成果物への反映が未完ならタグが揃っていても完了としない。
 
-### 実行主体
-メインセッション（model-routing.md の Architect ロール）が実行する。Sonnetへの再委任は行わない。
+## CLI・ゲートとの境界
 
-### レビュー手順
-1. Sonnetが出力したファイルを読み込む
-2. プロジェクトのレビュー基準に沿って検証する
-3. **スキル固有レビュー観点**を検証する
-4. 判定結果を出力する
+`skill:apply-cascade-update` は互換用のタグ追記CLIであり、設計本文の統合更新や意味レビューを代行しない。CLIの成功を本スキルの完了と扱わない。
 
-### スキル固有レビュー観点（BLOCK基準）
-- [ ] 変更が正しいレイヤーに帰属しているか（上位の抽象設計を汚していないか）
-- [ ] 変更理由が全箇所に記録されているか
-- [ ] 既存記述の不必要な削除がないか
-- [ ] 下位文書への影響が確認されているか
-- [ ] Phase 1の影響分析と実際の更新範囲が一致しているか
+storyReflectionで止まった場合は、エラーが示すWI・不足文書・反映先を確認し、inception／productを正規の順で修正してから再検証する。同じ根拠・revisionで解決済みなのに拒否が残る場合は、入力と診断を保存して原因を調査・引き継ぎ、保護解除や同一状態の無限再試行をしない。Quick Mode等の利用だけで設計整合や承認が済んだと推定しない。
 
-### 判定と修正
-- **BLOCK項目にFAIL** → Opusが直接修正してから完了とする
-- **WARNのみFAIL** → Opusが直接修正してから完了とする
-- **全PASS** → 完了
+ゲート設定の詳細は配備されたPhasegateの `docs/guide/configuration.md` とADR-013を必要時に参照する（consumerでは `node_modules/phasegate/docs/`、本リポジトリでは `docs/`）。

package/skills/cascade-updater/references//345/261/244/345/210/245/345/210/244/345/256/232/343/202/254/343/202/244/343/203/211.md

@@ -2,14 +2,16 @@
 
 変更・発見の種類ごとに、どのレイヤーの設計文書を更新すべきかの判定基準と具体例。
 
-## 環境設計に帰属するもの（最も頻度が高い）
+帰属と承認要否は別に判断する。頻度やファイル位置ではなく、変更で意味が変わる最上位の前提を確認する。以下の例でも、目的・契約・認可・不変条件に影響するならその決定へ戻る。
+
+## 環境設計に帰属するもの
 
 **判定基準:** コードの正しさではなく、環境の正しさに関する問題
 
 | パターン | 例 |
 |---------|-----|
 | 設定ファイルの漏れ | サービス/関数が設定ファイルに未登録 |
-| ランタイム制約 | 認証トークンのアルゴリズム不一致 |
+| ランタイム制約 | 合意済みランタイムと実行環境の不一致（認証アルゴリズムの変更は認可契約も確認） |
 | フレームワーク制約 | 特定ファイルからのexportルール、ビルド制約 |
 | シードデータ不足 | テストに必要なデータ層の欠落 |
 | マイグレーション漏れ | DB変更が適用されていない |
@@ -37,7 +39,7 @@
 | 状態遷移の不足 | 必要なドメインイベントが未定義 |
 | 不変条件の誤り | ビジネスルールの理解が間違っていた |
 
-## ストーリー/Unitに帰属するもの（非常にまれ）
+## ストーリー/Unitに帰属するもの
 
 **判定基準:** そもそも何を作るかの理解に関する問題
 

package/skills/release-publisher/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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 認証トラブルに関わる場面。
+description: Phasegate本体パッケージのリリースを依頼されたときのメンテナー向け手順。利用者プロジェクトのリリースや一般的なnpm認証相談には適用しない。
 model: sonnet
 review: opus
 languages: [typescript]
@@ -11,6 +11,8 @@ languages: [typescript]
 
 ## 目的
 
+対象はPhasegate本体のリポジトリだけ。以下の認証・バージョニング規則を利用者プロジェクトへ適用しない。publish、tag、pushはユーザーが依頼した範囲だけ実施する。対象や現行の公開手順が確認できない場合は先に確認する。
+
 phasegate パッケージのリリース（version bump → git tag → npm publish）を、誤操作・認証事故なしに完遂するための厳格手順ガイド（advisory）。正となる規範は `CLAUDE.md` の「バージョニングルール」「npm publish ルール」節、および `DEVELOPMENT.md` の「Versioning and Release」「Troubleshooting npm publish authentication」節。本スキルはそれらを実行手順として展開する。
 
 ## 絶対ルール（違反禁止）

package/skills/skill-creator/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: skill-creator
 kind: advisory
-description: phasegate バンドルのスキルを新規作成・改訂するための著者向けガイド。phasegate 固有の frontmatter 契約・正規見出し（skill-structure バリデータ）・モデル委任レンダリング・カタログ登録・日本語規約を扱う。スキルを追加/編集する際に使用する。
+description: Phasegate本体のバンドルスキルを追加・改訂するときのメンテナー向けガイド。利用者プロジェクト独自のスキル作成には適用しない。
 model: opus
 languages: [typescript]
 ---
@@ -57,8 +57,8 @@ phasegate のスキル frontmatter は `name` / `description` に加えて、他
 
 新規スキルは skill-structure バリデータ（`scripts/harness/skill-quality/domain/services/skill-structure-validator.ts`）に**必ず合格**する。バリデータはスキルの **kind** ごとに必須セクションを決める:
 
-- **lifecycle**（既定・23 スキル）: `frontmatter` / `languageMetadata` / `purpose` / `inputs` / `outputs` / `prerequisites` / `executionFlow` の 7 セクションを全保有すること。
-- **advisory**（allowlist の 7 スキル。本スキル含む）: `frontmatter` / `languageMetadata` / `purpose` の 3 セクションのみ必須。
+- **lifecycle**（既定）: `frontmatter` / `languageMetadata` / `purpose` / `inputs` / `outputs` / `prerequisites` / `executionFlow` の 7 セクションを全保有すること。
+- **advisory**（allowlist。本スキル含む）: `frontmatter` / `languageMetadata` / `purpose` の 3 セクションのみ必須。件数の正本は以下のcorpusテスト。
 
 ### セクション名 → 見出しの対応（sectionMap）
 
@@ -77,16 +77,15 @@ phasegate のスキル frontmatter は `name` / `description` に加えて、他
 ### kind の登録場所（allowlist / taxonomy）
 
 - kind 型と必須セクションの定義: `scripts/harness/skill-quality/domain/types/skill-kind.ts` と `.../value-objects/skill-structure.ts`。
-- **advisory allowlist の pin**: `scripts/harness/__tests__/integration/skill-quality/skill-corpus-conformance.test.ts` の `ADVISORY_SKILLS` 配列。ここに列挙された 7 件だけが `kind: advisory` を宣言でき、8 件目の自己宣言はテストが fail する。**advisory を増やす場合はこのテストの allowlist を意図的に更新すること**（lifecycle 要求の回避を防ぐ pin）。lifecycle スキルを追加する場合は allowlist 変更不要だが、7 セクションを全て満たす必要がある。
+- **advisory allowlist の pin**: `scripts/harness/__tests__/integration/skill-quality/skill-corpus-conformance.test.ts` の `ADVISORY_SKILLS` 配列。列挙されていない自己宣言はテストが fail する。**advisory を増やす場合はこのテストの allowlist を意図的に更新すること**（lifecycle 要求の回避を防ぐ pin）。lifecycle スキルを追加する場合は allowlist 変更不要だが、7 セクションを全て満たす必要がある。
 
 ## カタログ登録（新規スキル追加時に必須）
 
 新規スキルは SKILL.md を書くだけでは配信されない。以下のカタログ・件数 pin を必ず更新する:
 
-1. `scripts/harness/setup/skill-deployer.ts` の `SKILL_CATEGORIES`（`core` / `aidlc` / `utility` / `guidance` のいずれかに追加）。ここに載らないスキルは `getSkillsForSet` の配信対象にならない。
-2. `scripts/harness/installation/application/bundled-skill-selection.ts`（インストール時の選択ロジック）。
-3. 件数 pin: `skills/README.md`（"30 skills" の記述）・`docs/guide/skills-overview.md`（"30 skills"）。スキル総数を変えたら両方を同期更新する。
-4. advisory を追加する場合は前述の `skill-corpus-conformance.test.ts` の `ADVISORY_SKILLS` と、テスト内の件数期待値（`skills.length` / lifecycle・advisory の内訳）も更新する。
+1. 単一正本 `scripts/harness/installation/application/bundled-skill-selection.ts` のカテゴリと配布選択。setup側は委譲するためカタログを複製しない。consumerには本体用のrelease-publisher/skill-creatorを含めず、旧core/allの互換は維持する。
+2. `skills/README.md`・`docs/guide/skills-overview.md`の配布説明と件数を実体に合わせる。
+3. advisoryを追加する場合は前述のcorpusテストのallowlistと件数期待値も更新する。
 
 > なお `scripts/harness/` 配下のソース（`skill-deployer.ts` / `bundled-skill-selection.ts` 等）の変更はフェーズゲート対象であり、`quick-implementor` / `story-implementor` スキル経由で行う（CLAUDE.md 参照）。スキル本文（`skills/**` の docs）編集はゲート緩和対象。
 
@@ -113,5 +112,5 @@ phasegate のスキル frontmatter は `name` / `description` に加えて、他
 3. **雛形の用意** — 同種の既存スキル（lifecycle は例えば `unit-designer`、advisory は `phasegate-config-doctor`）の SKILL.md を土台にコピーし、frontmatter・見出しを埋める。
 4. **本文作成** — 日本語散文で。3 フェーズ系なら結合文字列をバイト単位で流用。詳細は `references/` へ切り出す。
 5. **構造検証** — `npx vitest run scripts/harness/__tests__/integration/skill-quality`（corpus-conformance）で宣言 kind の必須セクションに合格することを確認。
-6. **カタログ登録** — `SKILL_CATEGORIES` / `bundled-skill-selection.ts` / 件数 pin（README・skills-overview）を更新。
+6. **カタログ登録** — `bundled-skill-selection.ts`と関連する配布説明・corpus期待値を更新。
 7. **反復** — 実タスクで使い、SKILL.md / references を改善する。