phasegate 0.340.0 → 0.341.0

package/scripts/harness/phase-dependency-model/domain/services/story-reflection-checker.ts

@@ -1,12 +1,15 @@
 /**
  * @layer domain
  * @unit phase-dependency-model
+ * @work-item-id WI-220
  */
 
 import type { StoryReflectionFileSystemPort } from "../ports/story-reflection-file-system-port.js";
 import type { StoryReflectionConfig } from "../values/story-reflection-config.js";
 import type { StoryReflectionMapping } from "../values/story-reflection-mapping.js";
 import { StoryReflectionResult, type StoryReflectionViolation } from "../values/story-reflection-result.js";
+import type { WorkItemReflectionScope } from "./work-item-reflection-scope-resolver.js";
+import type { PathRoots } from "../values/artifact.js";
 
 const CROSS_WORK_ITEM_PATTERN = /^WI-\d+$/;
 
@@ -18,13 +21,50 @@ interface ResolvedInceptionPath {
 export class StoryReflectionChecker {
   constructor(private readonly fsPort: StoryReflectionFileSystemPort) {}
 
-  async check(unitId: string, config: StoryReflectionConfig): Promise<StoryReflectionResult> {
+  async check(unitId: string, config: StoryReflectionConfig, roots?: PathRoots): Promise<StoryReflectionResult> {
     if (!config.enabled) {
       return StoryReflectionResult.pass();
     }
 
     const storyIds = await this.fsPort.listStoryDirectories(unitId);
 
+    return this.checkItems(unitId, storyIds, config, false, roots);
+  }
+
+  /** Accept only a complete, caller-resolved scope; this method does not authenticate its origin. */
+  async checkResolvedScope(
+    scope: Extract<WorkItemReflectionScope, { status: 'complete' }>,
+    config: StoryReflectionConfig,
+    roots?: PathRoots,
+  ): Promise<StoryReflectionResult> {
+    if (!config.enabled) return StoryReflectionResult.pass();
+    if (scope.workItems.length === 0) throw new Error('Resolved reflection scope must not be empty');
+    const byUnit = new Map<string, Set<string>>();
+    for (const item of scope.workItems) {
+      for (const unit of item.unitIds) {
+        const ids = byUnit.get(unit) ?? new Set<string>();
+        ids.add(item.id);
+        byUnit.set(unit, ids);
+      }
+    }
+    const violations: StoryReflectionViolation[] = [];
+    const warnings: StoryReflectionViolation[] = [];
+    for (const [unit, ids] of byUnit) {
+      const result = await this.checkItems(unit, [...ids].sort(), config, true, roots);
+      violations.push(...result.violations);
+      warnings.push(...result.warnings);
+    }
+    return StoryReflectionResult.create({ violations, warnings });
+  }
+
+  private async checkItems(
+    unitId: string,
+    storyIds: readonly string[],
+    config: StoryReflectionConfig,
+    explicitScope: boolean,
+    roots?: PathRoots,
+  ): Promise<StoryReflectionResult> {
+
     if (storyIds.length === 0) {
       return StoryReflectionResult.pass();
     }
@@ -34,22 +74,24 @@ export class StoryReflectionChecker {
 
     for (const storyId of storyIds) {
       for (const mapping of config.mappings) {
-        const { product: productPath } = mapping.resolve({ unitId, storyId });
+        const { product: productPath } = mapping.resolve({ unitId, storyId }, roots);
         const resolvedInception = await this.resolveInceptionPath({
           mapping,
           unitId,
           storyId,
+          roots,
         });
 
         if (resolvedInception === null) {
           continue;
         }
 
-        if (resolvedInception.isCrossWorkItem && !(await this.fsPort.storyAffectsUnit(storyId, unitId))) {
+        if (!explicitScope && resolvedInception.isCrossWorkItem && !(await this.fsPort.storyAffectsUnit(storyId, unitId))) {
           continue;
         }
 
         if (
+          !explicitScope &&
           resolvedInception.isCrossWorkItem &&
           productPath.endsWith("domain_model.md") &&
           !(await this.fsPort.storyTouchesUnitLayer(storyId, unitId, "domain"))
@@ -83,11 +125,12 @@ export class StoryReflectionChecker {
     readonly mapping: StoryReflectionMapping;
     readonly unitId: string;
     readonly storyId: string;
+    readonly roots?: PathRoots;
   }): Promise<ResolvedInceptionPath | null> {
     const normalPath = input.mapping.resolve({
       unitId: input.unitId,
       storyId: input.storyId,
-    }).inception;
+    }, input.roots).inception;
 
     if (await this.fsPort.fileExists(normalPath)) {
       return { path: normalPath, isCrossWorkItem: false };
@@ -100,7 +143,7 @@ export class StoryReflectionChecker {
     const crossPath = input.mapping.resolve({
       unitId: "_cross",
       storyId: input.storyId,
-    }).inception;
+    }, input.roots).inception;
 
     if (await this.fsPort.fileExists(crossPath)) {
       return { path: crossPath, isCrossWorkItem: true };

package/scripts/harness/phase-dependency-model/domain/services/work-item-reflection-scope-resolver.ts

@@ -0,0 +1,64 @@
+// @unit phase-dependency-model
+// @layer domain
+// @work-item-id WI-220
+
+export interface WorkItemDependencyRecord {
+  readonly id: string;
+  readonly unitIds: readonly string[];
+  /** Missing is unknown; an explicit empty list declares no dependencies. */
+  readonly dependsOn?: readonly string[];
+}
+
+export type WorkItemScopeUnknownCode =
+  | 'NO_TARGET' | 'INVALID_ID' | 'MISSING_WORK_ITEM' | 'DUPLICATE_ID'
+  | 'UNIT_MISMATCH' | 'UNKNOWN_UNITS' | 'UNDECLARED_DEPENDENCIES';
+
+export type WorkItemReflectionScope =
+  | { readonly status: 'complete'; readonly workItems: readonly WorkItemDependencyRecord[] }
+  | { readonly status: 'unknown'; readonly code: WorkItemScopeUnknownCode; readonly workItemId?: string };
+
+/** Resolves declared dependencies only; it does not authenticate a session or approve design meaning. */
+export class WorkItemReflectionScopeResolver {
+  resolve(
+    unitId: string,
+    targetIds: readonly string[],
+    catalog: readonly WorkItemDependencyRecord[],
+  ): WorkItemReflectionScope {
+    const unknown = (code: WorkItemScopeUnknownCode, workItemId?: string): WorkItemReflectionScope =>
+      ({ status: 'unknown', code, workItemId });
+    if (targetIds.length === 0) return unknown('NO_TARGET');
+
+    const byId = new Map<string, WorkItemDependencyRecord[]>();
+    for (const item of catalog) {
+      const matches = byId.get(item.id);
+      if (matches) matches.push(item);
+      else byId.set(item.id, [item]);
+    }
+
+    const roots = new Set(targetIds);
+    const pending = [...roots].sort();
+    const visited = new Map<string, WorkItemDependencyRecord>();
+    // Iteration, rather than recursive traversal, also bounds work for cycles.
+    for (let index = 0; index < pending.length; index++) {
+      const id = pending[index];
+      if (visited.has(id)) continue;
+      if (!/^WI-\d+$/.test(id)) return unknown('INVALID_ID', id);
+      const matches = byId.get(id);
+      if (!matches) return unknown('MISSING_WORK_ITEM', id);
+      if (matches.length !== 1) return unknown('DUPLICATE_ID', id);
+      const item = matches[0];
+      if (item.unitIds.length === 0 || item.unitIds.some((unit) => !unit.trim() || unit.startsWith('_'))) {
+        return unknown('UNKNOWN_UNITS', id);
+      }
+      if (roots.has(id) && !item.unitIds.includes(unitId)) return unknown('UNIT_MISMATCH', id);
+      if (item.dependsOn === undefined) return unknown('UNDECLARED_DEPENDENCIES', id);
+      visited.set(id, item);
+      for (const dependency of new Set(item.dependsOn)) pending.push(dependency);
+    }
+
+    return {
+      status: 'complete',
+      workItems: [...visited.values()].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0),
+    };
+  }
+}

package/scripts/harness/phase-dependency-model/domain/values/story-reflection-mapping.ts

@@ -3,6 +3,8 @@
  * @unit phase-dependency-model
  */
 
+import type { PathRoots } from './artifact.js';
+
 export interface StoryReflectionMappingCreateArgs {
   readonly inception: string;
   readonly product: string;
@@ -69,7 +71,7 @@ export class StoryReflectionMapping {
     });
   }
 
-  resolve(scope: { unitId: string; storyId: string }): { inception: string; product: string } {
+  resolve(scope: { unitId: string; storyId: string }, roots?: PathRoots): { inception: string; product: string } {
     const inception = this.inception
       .replaceAll('{unit}', scope.unitId)
       .replaceAll('{storyId}', scope.storyId);
@@ -78,7 +80,11 @@ export class StoryReflectionMapping {
       .replaceAll('{unit}', scope.unitId)
       .replaceAll('{storyId}', scope.storyId);
 
-    return { inception, product };
+    if (!roots) return { inception, product };
+    return {
+      inception: inception.replace(/^docs\/inception\//, () => `${roots.inceptionDocsRoot}/`),
+      product: product.replace(/^docs\/product\/construction\//, () => `${roots.designDocsRoot}/`),
+    };
   }
 
   equals(other: StoryReflectionMapping): boolean {

package/scripts/harness/phase-dependency-model/infrastructure/filesystem/file-system-story-reflection-adapter.ts

@@ -27,6 +27,7 @@ export interface FileSystemStoryReflectionAdapterDeps {
   readonly rootDir: string;
   /** inception ディレクトリのルート（デフォルト: docs/inception） */
   readonly inceptionRoot?: string;
+  readonly designDocsRoot?: string;
 }
 
 /**
@@ -43,11 +44,13 @@ export interface FileSystemStoryReflectionAdapterDeps {
 export class FileSystemStoryReflectionAdapter implements StoryReflectionFileSystemPort {
   private readonly rootDir: string;
   private readonly inceptionRoot: string;
+  private readonly designDocsRoot: string;
   private readonly changedPathsByStoryId = new Map<string, Promise<ReadonlySet<string>>>();
 
   constructor(deps: FileSystemStoryReflectionAdapterDeps) {
     this.rootDir = deps.rootDir;
     this.inceptionRoot = deps.inceptionRoot ?? "docs/inception";
+    this.designDocsRoot = deps.designDocsRoot ?? "docs/product/construction";
   }
 
   async listStoryDirectories(unitId: string): Promise<readonly string[]> {
@@ -325,7 +328,9 @@ export class FileSystemStoryReflectionAdapter implements StoryReflectionFileSyst
 
   private extractProductUnitId(productPath: string): string | null {
     const normalized = productPath.split(path.sep).join("/");
-    const match = /^docs\/product\/construction\/([^/]+)\//.exec(normalized);
+    const prefix = `${this.designDocsRoot}/`;
+    if (!normalized.startsWith(prefix)) return null;
+    const match = /^([^/]+)\//.exec(normalized.slice(prefix.length));
     return match?.[1] ?? null;
   }
 

package/scripts/harness/phase-dependency-model/infrastructure/filesystem/file-system-work-item-dependency-catalog.ts

@@ -0,0 +1,73 @@
+// @unit phase-dependency-model
+// @layer infrastructure
+// @work-item-id WI-220
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, resolve, sep } from 'node:path';
+import type { WorkItemDependencyRecord } from '../../domain/services/work-item-reflection-scope-resolver.js';
+import type { WorkItemFrontmatter } from '../../../traceability-model/domain/value-objects/work-item-frontmatter.js';
+import { parseWorkItemDependencies, parseWorkItemFrontmatter } from '../../../traceability-model/infrastructure/parsers/work-item-frontmatter-parser.js';
+
+export interface WorkItemDependencyCatalogEntry extends WorkItemDependencyRecord {
+  readonly descriptionPath: string;
+  readonly metadata?: WorkItemFrontmatter;
+  readonly diagnostic?: string;
+}
+
+interface IndexedDescription {
+  readonly owner: string;
+  readonly path: string;
+}
+
+/** Directory index is global, document reads are limited to reachable WI IDs. */
+export class FileSystemWorkItemDependencyCatalog {
+  constructor(private readonly options: { rootDir: string; inceptionRoot?: string }) {}
+
+  async load(targetIds: readonly string[]): Promise<readonly WorkItemDependencyCatalogEntry[]> {
+    const root = resolve(this.options.rootDir, this.options.inceptionRoot ?? 'docs/inception');
+    const index = new Map<string, IndexedDescription[]>();
+    const owners = await readdir(root, { withFileTypes: true });
+    for (const owner of owners.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (!owner.isDirectory() || owner.name.startsWith('.') || (owner.name.startsWith('_') && owner.name !== '_cross')) continue;
+      const entries = await readdir(join(root, owner.name), { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory() || !/^WI-\d+$/.test(entry.name)) continue;
+        const descriptions = index.get(entry.name) ?? [];
+        descriptions.push({ owner: owner.name, path: join(root, owner.name, entry.name, 'description.md') });
+        index.set(entry.name, descriptions);
+      }
+    }
+
+    const pending = [...new Set(targetIds)].sort();
+    const visited = new Set<string>();
+    const result: WorkItemDependencyCatalogEntry[] = [];
+    for (let cursor = 0; cursor < pending.length; cursor++) {
+      const id = pending[cursor];
+      if (visited.has(id)) continue;
+      visited.add(id);
+      // Only indexed paths are read; an input ID is never used to construct a path.
+      for (const description of index.get(id) ?? []) {
+        const entry = await this.readEntry(id, description);
+        result.push(entry);
+        for (const dependency of entry.dependsOn ?? []) pending.push(dependency);
+      }
+    }
+    return result;
+  }
+
+  private async readEntry(id: string, description: IndexedDescription): Promise<WorkItemDependencyCatalogEntry> {
+    const descriptionPath = relative(this.options.rootDir, description.path).split(sep).join('/');
+    try {
+      const content = await readFile(description.path, 'utf8');
+      const metadata = parseWorkItemFrontmatter(content);
+      if (metadata === null || metadata.id !== id) throw new Error('WI frontmatter id must match its directory');
+      const dependsOn = parseWorkItemDependencies(content);
+      const unitIds = metadata.affects ?? (description.owner === '_cross' ? [] : [description.owner]);
+      if (unitIds.length === 0 || unitIds.some((unit) => !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(unit))) {
+        throw new Error('WI owner/affects must identify actual Units');
+      }
+      return { id, unitIds, dependsOn, descriptionPath, metadata };
+    } catch (error) {
+      return { id, unitIds: [], descriptionPath, diagnostic: error instanceof Error ? error.message : String(error) };
+    }
+  }
+}

package/scripts/harness/quick-mode/application/dto/change-category-classification-contract.ts

@@ -1,6 +1,9 @@
 // @unit quick-mode
 // @layer application
 // @story H10-05
+// @work-item-id WI-220
+
+import type { ChangeRiskAdvice } from '../ports/change-risk-advisory-port.js';
 
 export interface ChangeCategoryPerFile {
   readonly path: string;
@@ -8,6 +11,7 @@ export interface ChangeCategoryPerFile {
 }
 
 export interface ChangeCategoryClassificationContract {
+  readonly riskAdvice?: readonly ChangeRiskAdvice[];
   readonly dominantCategory: string | null;
   readonly perFile: readonly ChangeCategoryPerFile[];
   readonly fullModeRequired: boolean;

package/scripts/harness/quick-mode/application/ports/change-risk-advisory-port.ts

@@ -0,0 +1,16 @@
+// @unit quick-mode
+// @layer application
+// @work-item-id WI-220
+export interface ChangeRiskAdvice {
+  readonly path: string;
+  readonly kind: 'module-surface-change' | 'behavior-review' | 'unknown' | 'no-content-change';
+  readonly source: 'caller-snapshot';
+  readonly enforcement: 'none';
+  readonly beforeHash: string | null;
+  readonly afterHash: string | null;
+  readonly reason: string;
+}
+
+export interface ChangeRiskAdvisoryPort {
+  assess(paths: readonly string[], snapshotFile: string): Promise<readonly ChangeRiskAdvice[]>;
+}

package/scripts/harness/quick-mode/composition-root.ts

@@ -13,6 +13,7 @@ import { JudgeQuickModeEligibilityUseCase } from "./application/usecases/judge-q
 import { QuickModeJudgmentEngine } from "./domain/services/quick-mode-judgment-engine.js";
 import { ValidatorRelaxationService } from "./domain/services/validator-relaxation-service.js";
 import { FsFileExistenceAdapter } from "./infrastructure/adapters/fs-file-existence-adapter.js";
+import { SnapshotRiskAdvisoryAdapter } from "./infrastructure/adapters/snapshot-risk-advisory-adapter.js";
 import { GitDiffChangedFilesAdapter } from "./infrastructure/adapters/git-diff-changed-files-adapter.js";
 import { HarnessConfigQuickModeConfigAdapter } from "./infrastructure/adapters/harness-config-quick-mode-config-adapter.js";
 import { ValidatorSystemQuickModeExecutionAdapter } from "./infrastructure/adapters/validator-system-quick-mode-execution-adapter.js";
@@ -86,7 +87,10 @@ export function createQuickModeCompositionRoot(
 
   // Presentation
   const handler = new CiCheckQuickModeHandler({ useCase: executeUseCase });
-  const checkChangeCategoryHandler = new CheckChangeCategoryHandler({ useCase: classifyUseCase });
+  const checkChangeCategoryHandler = new CheckChangeCategoryHandler({
+    useCase: classifyUseCase,
+    riskAdvisoryPort: new SnapshotRiskAdvisoryAdapter(options.rootDir),
+  });
 
   return {
     handler,

package/scripts/harness/quick-mode/infrastructure/adapters/snapshot-risk-advisory-adapter.ts

@@ -0,0 +1,118 @@
+// @unit quick-mode
+// @layer infrastructure
+// @work-item-id WI-220
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type * as TypeScript from 'typescript';
+import type { ChangeRiskAdvice, ChangeRiskAdvisoryPort } from '../../application/ports/change-risk-advisory-port.js';
+
+interface Snapshot {
+  filePath: string;
+  beforeContent: string | null;
+  afterContent: string | null;
+}
+
+function isSnapshot(value: unknown): value is Snapshot {
+  if (typeof value !== 'object' || value === null) return false;
+  const item = value as Record<string, unknown>;
+  return typeof item.filePath === 'string' && item.filePath.length > 0
+    && (typeof item.beforeContent === 'string' || item.beforeContent === null)
+    && (typeof item.afterContent === 'string' || item.afterContent === null);
+}
+
+function hash(content: string | null): string | null {
+  return content === null ? null : createHash('sha256').update(content).digest('hex');
+}
+
+function classSurface(ts: typeof TypeScript, declaration: TypeScript.ClassDeclaration): TypeScript.ClassDeclaration | null {
+  const decorated = (node: TypeScript.Node) => ts.canHaveDecorators(node) && (ts.getDecorators(node)?.length ?? 0) > 0;
+  if (decorated(declaration)) return null;
+  const members: TypeScript.ClassElement[] = [];
+  for (const member of declaration.members) {
+    if (decorated(member)) return null;
+    if (ts.isMethodDeclaration(member) || ts.isConstructorDeclaration(member)) {
+      if (member.parameters.some(parameter => !parameter.type || parameter.initializer || decorated(parameter))) return null;
+      if (ts.isMethodDeclaration(member)) {
+        if (!member.type || member.asteriskToken) return null;
+        members.push(ts.factory.updateMethodDeclaration(member, member.modifiers, member.asteriskToken,
+          member.name, member.questionToken, member.typeParameters, member.parameters, member.type, undefined));
+      } else members.push(ts.factory.updateConstructorDeclaration(member, member.modifiers, member.parameters, undefined));
+    } else if (ts.isPropertyDeclaration(member)) {
+      if (!member.type) return null;
+      members.push(ts.factory.updatePropertyDeclaration(member, member.modifiers, member.name,
+        member.questionToken ?? member.exclamationToken, member.type, undefined));
+    } else return null;
+  }
+  return ts.factory.updateClassDeclaration(declaration, declaration.modifiers, declaration.name,
+    declaration.typeParameters, declaration.heritageClauses, members);
+}
+
+// A deliberately bounded module-surface observation, not an API or behavior proof.
+function surface(ts: typeof TypeScript, path: string, content: string): string | null {
+  const diagnostics = ts.transpileModule(content, { fileName: path, reportDiagnostics: true }).diagnostics ?? [];
+  if (diagnostics.some((item) => item.category === ts.DiagnosticCategory.Error)) return null;
+  const file = ts.createSourceFile(path, content, ts.ScriptTarget.Latest, true);
+  const printer = ts.createPrinter({ removeComments: true });
+  const declarations: string[] = [];
+  for (const statement of file.statements) {
+    if (ts.isExportDeclaration(statement) || ts.isExportAssignment(statement)) return null;
+    const exported = ts.canHaveModifiers(statement)
+      && ts.getModifiers(statement)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+    if (!exported) continue;
+    let declaration: TypeScript.Node = statement;
+    if (ts.isFunctionDeclaration(statement)) {
+      if (!statement.type || statement.parameters.some((parameter) => !parameter.type || parameter.initializer)
+        || statement.asteriskToken) return null;
+      declaration = ts.factory.updateFunctionDeclaration(statement, statement.modifiers, statement.asteriskToken,
+        statement.name, statement.typeParameters, statement.parameters, statement.type, undefined);
+    } else if (ts.isClassDeclaration(statement)) {
+      const observed = classSurface(ts, statement);
+      if (observed === null) return null;
+      declaration = observed;
+    } else if (!ts.isInterfaceDeclaration(statement) && !ts.isTypeAliasDeclaration(statement)) {
+      return null;
+    }
+    declarations.push(printer.printNode(ts.EmitHint.Unspecified, declaration, file));
+  }
+  return declarations.join('\n');
+}
+
+export class SnapshotRiskAdvisoryAdapter implements ChangeRiskAdvisoryPort {
+  constructor(private readonly rootDir: string = process.cwd()) {}
+
+  async assess(paths: readonly string[], snapshotFile: string): Promise<readonly ChangeRiskAdvice[]> {
+    const raw: unknown = JSON.parse(await readFile(resolve(this.rootDir, snapshotFile), 'utf8'));
+    if (!Array.isArray(raw) || !raw.every(isSnapshot)) {
+      throw new Error('Risk snapshots must be an array of { filePath, beforeContent: string|null, afterContent: string|null }.');
+    }
+    // No TypeScript runtime loading or source parsing occurs on the default classification path.
+    const ts = await import('typescript');
+    return paths.map((path) => {
+      const matches = raw.filter((snapshot) => snapshot.filePath === path);
+      const snapshot = matches.length === 1 ? matches[0] : undefined;
+      const before = snapshot?.beforeContent ?? null;
+      const after = snapshot?.afterContent ?? null;
+      const base = { path, source: 'caller-snapshot' as const, enforcement: 'none' as const,
+        beforeHash: hash(before), afterHash: hash(after) };
+      if (!snapshot || before === null || after === null) {
+        return { ...base, kind: 'unknown', reason: 'Missing, duplicate, creation or deletion snapshot: inspect the actual revision and affected contracts.' };
+      }
+      if (before === after) {
+        return { ...base, kind: 'no-content-change', reason: 'Only the supplied snapshots are identical; this is not approval or verification of the current revision.' };
+      }
+      if (!/\.[cm]?tsx?$/.test(path) || /\.d\.[cm]?ts$/.test(path)) {
+        return { ...base, kind: 'unknown', reason: 'Unsupported source language: inspect the contract and behavior changes.' };
+      }
+      const beforeSurface = surface(ts, path, before);
+      const afterSurface = surface(ts, path, after);
+      if (beforeSurface === null || afterSurface === null) {
+        return { ...base, kind: 'unknown', reason: 'Invalid or unsupported declaration: inspect exported contracts, authorization, invariants and persisted formats.' };
+      }
+      if (beforeSurface !== afterSurface) {
+        return { ...base, kind: 'module-surface-change', reason: 'Declared module surface changed. Confirm public consumers and escalate changes to agreed contracts before dependent work.' };
+      }
+      return { ...base, kind: 'behavior-review', reason: 'Declared module surface is unchanged, but behavior equivalence is unproven. Review authorization, business invariants and persisted formats; internal extraction is not automatically approved.' };
+    });
+  }
+}

package/scripts/harness/quick-mode/presentation/formatters/change-category-formatter.ts

@@ -37,6 +37,13 @@ export class ChangeCategoryFormatter {
       }
     }
 
+    if (contract.riskAdvice !== undefined) {
+      lines.push('riskAdvice (caller snapshots; advisory only, existing gate unchanged):');
+      for (const advice of contract.riskAdvice) {
+        lines.push(`  ${advice.path} -> ${advice.kind}: ${advice.reason}`);
+        lines.push(`    before=${advice.beforeHash ?? 'unknown'} after=${advice.afterHash ?? 'unknown'}`);
+      }
+    }
     return lines.join('\n') + '\n';
   }
 }

package/scripts/harness/quick-mode/presentation/handlers/check-change-category-handler.ts

@@ -7,17 +7,20 @@
  */
 
 import type { ClassifyChangeCategoryUseCase } from '../../application/usecases/classify-change-category-usecase.js';
+import type { ChangeRiskAdvisoryPort } from '../../application/ports/change-risk-advisory-port.js';
 import { ChangeCategoryFormatter, type ChangeCategoryOutputFormat } from '../formatters/change-category-formatter.js';
 
 export interface CheckChangeCategoryHandlerDeps {
   useCase: Pick<ClassifyChangeCategoryUseCase, 'execute'>;
   writer?: (s: string) => void;
+  riskAdvisoryPort?: ChangeRiskAdvisoryPort;
 }
 
 export interface CheckChangeCategoryHandlerOptions {
   paths?: string;
   format?: ChangeCategoryOutputFormat;
   failOnFullRequired?: boolean;
+  riskSnapshots?: string;
 }
 
 export interface CheckChangeCategoryHandlerResult {
@@ -28,9 +31,11 @@ export class CheckChangeCategoryHandler {
   private readonly useCase: Pick<ClassifyChangeCategoryUseCase, 'execute'>;
   private readonly writer: (s: string) => void;
   private readonly formatter = new ChangeCategoryFormatter();
+  private readonly riskAdvisoryPort?: ChangeRiskAdvisoryPort;
 
   constructor(deps: CheckChangeCategoryHandlerDeps) {
     this.useCase = deps.useCase;
+    this.riskAdvisoryPort = deps.riskAdvisoryPort;
     this.writer = deps.writer ?? ((s: string) => process.stdout.write(s));
   }
 
@@ -41,7 +46,13 @@ export class CheckChangeCategoryHandler {
       ? pathsRaw.split(',').map((p) => p.trim()).filter((p) => p.length > 0)
       : [];
 
-    const contract = await this.useCase.execute({ paths });
+    const classification = await this.useCase.execute({ paths });
+    if (options.riskSnapshots !== undefined && this.riskAdvisoryPort === undefined) {
+      throw new Error('Risk advisory is not available in this handler configuration.');
+    }
+    const contract = options.riskSnapshots !== undefined
+      ? { ...classification, riskAdvice: await this.riskAdvisoryPort!.assess(paths, options.riskSnapshots) }
+      : classification;
     this.writer(this.formatter.format(contract, format));
 
     const exitCode = failOnFullRequired && contract.fullModeRequired ? 1 : 0;

package/scripts/harness/setup/skill-deployer.ts

@@ -10,6 +10,8 @@
 
 import { promises as fs } from "node:fs";
 import { dirname, join } from "node:path";
+import { getBundledSkillsForSet, SKILL_CATEGORIES, type SkillCategory, type SkillSet } from "../installation/application/bundled-skill-selection.js";
+export { SKILL_CATEGORIES, type SkillCategory, type SkillSet } from "../installation/application/bundled-skill-selection.js";
 
 const HARNESS_VERSION_FILE = ".harness-version";
 const SKILLS_SOURCE_DIR = "skills";
@@ -25,52 +27,8 @@ const DEFAULT_FOLDER_RULES_DOC = join("docs", "folder_management_rules.md");
 
 // ── Skill Category Map ──
 
-export type SkillCategory = "core" | "aidlc" | "utility" | "guidance";
-export type SkillSet = "core" | "all";
-
-export const SKILL_CATEGORIES: Record<SkillCategory, readonly string[]> = {
-  core: [
-    "cascade-updater",
-    "codebase-mapper",
-    "consistency-checker",
-    "doc-health-checker",
-    "engineering-perspective",
-    "implementation-readiness-checker",
-    "test-coverage-checker",
-  ],
-  aidlc: [
-    "domain-designer",
-    "environment-designer",
-    "it-test-designer",
-    "it-test-logic-designer",
-    "logical-designer",
-    "mock-designer",
-    "product-architect",
-    "quick-implementor",
-    "scenario-test-designer",
-    "scenario-test-logic-designer",
-    "story-implementor",
-    "story-mapper",
-    "story-writer",
-    "uiux-designer",
-    "unit-designer",
-    "unit-test-designer",
-    "unit-test-logic-designer",
-  ],
-  utility: ["codex-delegator", "skill-creator"],
-  guidance: ["phasegate-toolkit-guide", "phasegate-config-doctor", "release-publisher"],
-} as const;
-
 export function getSkillsForSet(skillSet: SkillSet): string[] {
-  if (skillSet === "core") {
-    return [...SKILL_CATEGORIES.core];
-  }
-  return [
-    ...SKILL_CATEGORIES.core,
-    ...SKILL_CATEGORIES.aidlc,
-    ...SKILL_CATEGORIES.utility,
-    ...SKILL_CATEGORIES.guidance,
-  ];
+  return getBundledSkillsForSet(skillSet);
 }
 
 export function getCategoryForSkill(skillName: string): SkillCategory | null {

package/scripts/harness/skill-quality/application/dto/run-plan-checker-loop-output.ts

@@ -9,4 +9,5 @@ export interface RunPlanCheckerLoopOutput {
   readonly status: LoopStatus;
   readonly loopHistory: readonly LoopAttempt[];
   readonly escalationRequired: boolean;
+  readonly stopReason?: 'UNCHANGED_INPUT';
 }

package/scripts/harness/skill-quality/application/usecases/apply-cascade-update-usecase.ts

@@ -2,6 +2,7 @@
  * @layer application
  * @unit skill-quality
  * @work-item-id WI-192
+ * @work-item-id WI-220
  */
 import { CascadeUpdateResult } from '../../domain/value-objects/cascade-update-result.js';
 import type { CascadeUpdateService } from '../../domain/services/cascade-update-service.js';
@@ -21,6 +22,7 @@ export class ApplyCascadeUpdateUseCase {
     let updatedCount = 0;
     const appliedStoryIds: string[] = [];
     const errors: string[] = [];
+    const visitedFiles = new Set<string>();
 
     for (const target of targets) {
       try {
@@ -30,13 +32,16 @@ export class ApplyCascadeUpdateUseCase {
           : [target.filePath];
 
         for (const filePath of filePaths) {
+          if (visitedFiles.has(filePath)) continue;
+          visitedFiles.add(filePath);
           try {
             const content = await this.fileSystemPort.read(filePath);
-            // Append story-id tag if not already present
-            const updatedContent = content.includes(target.storyIdTag)
+            // This is exact tag presence, not proof of semantic reflection.
+            const updatedContent = target.hasAnnotationIn(content)
               ? content
-              : `${content}\n${target.storyIdTag}`;
-            if (!input.dryRun && updatedContent !== content) {
+              : `${content}\n${target.renderAnnotation(filePath)}`;
+            if (updatedContent === content) continue;
+            if (!input.dryRun) {
               await this.fileSystemPort.write(filePath, updatedContent);
             }
             updatedCount++;