phasegate 0.315.0 → 0.335.0

package/scripts/harness/config-foundation/infrastructure/schemas/harness-config-v3.schema.json

@@ -13,6 +13,18 @@
     "decisionSignal": {
       "type": "string",
       "enum": ["business-rule-branch", "validation-rule", "error-construction", "state-transition", "policy-selection"]
+    },
+    "changeCategory": {
+      "type": "string",
+      "enum": ["bugfix", "docs", "test", "config", "feature", "domain", "api"]
+    },
+    "categoryOverrideGlobs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
     }
   },
   "properties": {
@@ -170,9 +182,10 @@
       "additionalProperties": false,
       "properties": {
         "allowedCategories": {
+          "description": "Quick Mode を通過させる ChangeCategory。7 値の enum で、未知値は設定エラーとして拒否される。",
           "type": "array",
           "items": {
-            "type": "string"
+            "$ref": "#/$defs/changeCategory"
           },
           "uniqueItems": true
         },
@@ -204,6 +217,34 @@
               "type": "boolean"
             }
           }
+        },
+        "categoryOverrides": {
+          "description": "プロジェクト固有パスを任意の ChangeCategory へ割り当てる glob ルール。組み込み分類より先に評価されるが、組み込みが domain / api のファイルは降格できない。",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "bugfix": {
+              "$ref": "#/$defs/categoryOverrideGlobs"
+            },
+            "docs": {
+              "$ref": "#/$defs/categoryOverrideGlobs"
+            },
+            "test": {
+              "$ref": "#/$defs/categoryOverrideGlobs"
+            },
+            "config": {
+              "$ref": "#/$defs/categoryOverrideGlobs"
+            },
+            "feature": {
+              "$ref": "#/$defs/categoryOverrideGlobs"
+            },
+            "domain": {
+              "$ref": "#/$defs/categoryOverrideGlobs"
+            },
+            "api": {
+              "$ref": "#/$defs/categoryOverrideGlobs"
+            }
+          }
         }
       }
     },

package/scripts/harness/harness-api/domain/value-objects/known-harness-commands.ts

@@ -1,6 +1,6 @@
 // @unit harness-api
 // @layer domain
-// @work-item-id WI-250, WI-291, WI-296
+// @work-item-id WI-250, WI-291, WI-296, WI-367, WI-368
 // known-harness-commands.ts — CLI 実サーフェスの canonical 既知コマンド一覧
 //
 // main.ts の CLI dispatch（`switch (command)`）が受理する全トップレベルコマンド名の
@@ -70,6 +70,7 @@ export const KNOWN_HARNESS_COMMANDS: readonly string[] = Object.freeze([
   "regression:run-k14-k15",
   "render-errors",
   "scaffold-design",
+  "scaffold-inception",
   "scaffold-wi",
   "session",
   "setup:agent",
@@ -80,6 +81,7 @@ export const KNOWN_HARNESS_COMMANDS: readonly string[] = Object.freeze([
   "skill:validate-structure",
   "skills",
   "status",
+  "templates",
   "uninstall",
   "update-skills",
   "validate",

package/scripts/harness/main.ts

@@ -45,7 +45,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createAdrFoundationModule } from "./adr-foundation/composition-root.js";
 import { createBiomeAstEngineModule } from "./biome-ast-engine/composition-root.js";
-import { buildCiGovernance } from "./ci-governance/composition-root.js";
+import { buildCiGovernance, type CiGovernanceDocPaths } from "./ci-governance/composition-root.js";
 import { toPhaseConfigSection } from "./config-foundation/application/mappers/phase-config-section-mapper.js";
 import { toValidatorSystemConfig } from "./config-foundation/application/mappers/validator-system-config-mapper.js";
 import { toWorldModelConfig } from "./config-foundation/application/mappers/world-model-config-mapper.js";
@@ -120,6 +120,19 @@ function toTraceabilityModelOptions(resolvedConfig: HarnessConfigV2 | undefined)
   return resolvedConfig ? { pathRoots: { designDocsRoot: resolvedConfig.paths.designDocs } } : undefined;
 }
 
+/**
+ * WI-369: ci-governance の scaffold 系アダプタに解決済み paths を渡す。
+ * これが無いと `scaffold-design` の書き込み先が `docs/product/construction` に
+ * 固定され、`paths.designDocs` を移設した PJ で scaffold 先とゲート検査先がズレる。
+ */
+function toCiGovernanceDocPaths(resolvedConfig: HarnessConfigV2 | undefined): CiGovernanceDocPaths {
+  if (!resolvedConfig) return {};
+  return {
+    designDocs: resolvedConfig.paths.designDocs,
+    inceptionDocs: resolvedConfig.paths.inceptionDocs,
+  };
+}
+
 interface PackageJsonDocument {
   readonly [key: string]: unknown;
   readonly dependencies?: unknown;
@@ -263,6 +276,7 @@ Gate semantics:
   ci:check-repetition          Check error repetition (--code <errorCode>, --reset, --json)
   baseline                     Create retrofit baseline snapshot (--dry-run, --force, --paths <glob,glob,...>, --json)
   scaffold-design              Scaffold a design doc (--unit <id>, --phase <logical|domain|uiux|unit-test|it-test>, --dry-run|--apply, --force, --json)
+  scaffold-inception           Scaffold an inception/product doc (--kind <product-overview-plan|product-overview|story-writer-plan|story-mapping-plan|unit-design-plan>, --dry-run|--apply, --force, --json)
   session begin                Start a Full Mode session (--mode full, --unit, --work-item, --reason, --duration)
   session end                  End a Full Mode session (--work-item)
 
@@ -294,6 +308,10 @@ Skills:
   skills list                  List all available skills
   skills info <name>           Show skill details (SKILL.md)
 
+Templates:
+  templates list               List bundled document templates
+  templates show <name>        Print a bundled template to stdout
+
 Options:
   --help                       Show this help message
   --version                    Show version number
@@ -900,6 +918,33 @@ Options:
   --force                    Overwrite an existing target when applying.
   --json                     Output machine-readable JSON.
   --help, -h                 Show this help`,
+  "scaffold-inception": `Usage: phasegate scaffold-inception --kind <doc-kind> [options]
+
+Scaffold an inception plan document or the product overview.
+Targets follow paths.inceptionDocs / paths.designDocs from phasegate.config.json.
+
+Options:
+  --kind <doc-kind>          product-overview-plan, product-overview, story-writer-plan,
+                             story-mapping-plan, or unit-design-plan.
+  --dry-run                  Preview target and template without writing (default).
+  --apply                    Write the scaffold.
+  --force                    Overwrite an existing target when applying.
+  --json                     Output machine-readable JSON.
+  --help, -h                 Show this help`,
+  templates: `Usage: phasegate templates <list|show <name>>
+
+Print bundled document templates to stdout, without reading node_modules.
+
+Subcommands:
+  list                       List available template names.
+  show <name>                Print the template body to stdout.
+
+Options:
+  --json                     Output machine-readable JSON (list only).
+  --help, -h                 Show this help
+
+Notes:
+  <name> is matched against the bundled template catalog. Paths are rejected.`,
   session: `Usage: phasegate session <begin|end> [options]
 
 Manage hook-visible Full Mode sessions.
@@ -2965,7 +3010,10 @@ async function main(): Promise<void> {
       case "ci-check": {
         const quick = hasFlag(args, "--quick");
         if (quick) {
-          const mod = createQuickModeCompositionRoot();
+          // WI-364: check-change-category (WI-351) と同様に解決済み configPath / rootDir を注入する。
+          // 無指定だと quickMode 設定を cwd 基準でしか探せず、サブディレクトリ実行で
+          // HarnessConfigNotFoundError → exit 2 になっていた。
+          const mod = createQuickModeCompositionRoot(await resolveQuickModeCompositionOptions());
           const failOnReject = hasFlag(args, "--fail-on-reject");
           const dryRun = hasFlag(args, "--dry-run");
           const files = parseFlag(args, "--files");
@@ -3241,7 +3289,7 @@ Examples:
           console.error(flagError);
           process.exit(2);
         }
-        const mod = buildCiGovernance(rootDir, harnessRoot);
+        const mod = buildCiGovernance(rootDir, harnessRoot, toCiGovernanceDocPaths(resolvedConfig));
         const presetId = parseFlag(args, "--preset") ?? "standard";
         const templateType = parseFlag(args, "--type") ?? "aidlc-gate";
         const render = hasFlag(args, "--render");
@@ -3253,7 +3301,7 @@ Examples:
       }
 
       case "ci:migrate-agents-md": {
-        const mod = buildCiGovernance(rootDir, harnessRoot);
+        const mod = buildCiGovernance(rootDir, harnessRoot, toCiGovernanceDocPaths(resolvedConfig));
         const dryRun = hasFlag(args, "--dry-run");
         const validateOnly = hasFlag(args, "--validate-only");
         const format = json ? "json" : "human";
@@ -3264,7 +3312,7 @@ Examples:
       }
 
       case "ci:auto-refresh-agent-context": {
-        const mod = buildCiGovernance(rootDir, harnessRoot);
+        const mod = buildCiGovernance(rootDir, harnessRoot, toCiGovernanceDocPaths(resolvedConfig));
         const dryRun = hasFlag(args, "--dry-run");
         const apply = hasFlag(args, "--apply");
         const format = json ? "json" : "human";
@@ -3275,7 +3323,7 @@ Examples:
       }
 
       case "refresh-claude-md": {
-        const mod = buildCiGovernance(rootDir, harnessRoot);
+        const mod = buildCiGovernance(rootDir, harnessRoot, toCiGovernanceDocPaths(resolvedConfig));
         const dryRun = hasFlag(args, "--dry-run");
         const apply = hasFlag(args, "--apply");
         const format = json ? "json" : "human";
@@ -3286,7 +3334,7 @@ Examples:
       }
 
       case "p2:check-agent-context": {
-        const mod = buildCiGovernance(rootDir, harnessRoot);
+        const mod = buildCiGovernance(rootDir, harnessRoot, toCiGovernanceDocPaths(resolvedConfig));
         const thresholdRaw = parseFlag(args, "--threshold-days");
         const thresholdDays = thresholdRaw === undefined ? undefined : Number(thresholdRaw);
         const format = json ? "json" : "human";
@@ -3297,7 +3345,7 @@ Examples:
       }
 
       case "ci:check-repetition": {
-        const mod = buildCiGovernance(rootDir, harnessRoot);
+        const mod = buildCiGovernance(rootDir, harnessRoot, toCiGovernanceDocPaths(resolvedConfig));
         const errorCode = parseFlag(args, "--code") ?? "";
         const reset = hasFlag(args, "--reset");
         const format = json ? "json" : "human";
@@ -3308,7 +3356,7 @@ Examples:
       }
 
       case "baseline": {
-        const mod = buildCiGovernance(rootDir, harnessRoot);
+        const mod = buildCiGovernance(rootDir, harnessRoot, toCiGovernanceDocPaths(resolvedConfig));
         const dryRun = hasFlag(args, "--dry-run");
         const force = hasFlag(args, "--force");
         const pathsFlag = parseFlag(args, "--paths");
@@ -3331,7 +3379,7 @@ Examples:
       }
 
       case "scaffold-design": {
-        const mod = buildCiGovernance(rootDir, harnessRoot);
+        const mod = buildCiGovernance(rootDir, harnessRoot, toCiGovernanceDocPaths(resolvedConfig));
         const unit = parseFlag(args, "--unit") ?? "";
         const phase = parseFlag(args, "--phase") ?? "";
         const dryRun = hasFlag(args, "--dry-run");
@@ -3351,8 +3399,50 @@ Examples:
         return;
       }
 
+      case "scaffold-inception": {
+        const mod = buildCiGovernance(rootDir, harnessRoot, toCiGovernanceDocPaths(resolvedConfig));
+        const kind = parseFlag(args, "--kind") ?? "";
+        const dryRun = hasFlag(args, "--dry-run");
+        const apply = hasFlag(args, "--apply");
+        const force = hasFlag(args, "--force");
+        const format = json ? "json" : "human";
+        const result = await mod.scaffoldInceptionHandler.handle({
+          kind,
+          dryRun,
+          apply,
+          force,
+          format,
+        });
+        console.log(result.output);
+        await finishCliExit(result.exitCode);
+        return;
+      }
+
+      case "templates": {
+        const mod = buildCiGovernance(rootDir, harnessRoot, toCiGovernanceDocPaths(resolvedConfig));
+        const subCommand = args[1];
+        const emit = async (result: { exitCode: number; output: string; errorOutput: string }): Promise<void> => {
+          if (result.output.length > 0) console.log(result.output);
+          if (result.errorOutput.length > 0) console.error(result.errorOutput);
+          await finishCliExit(result.exitCode);
+        };
+
+        if (subCommand === "list") {
+          await emit(await mod.templatesHandler.list({ format: json ? "json" : "human" }));
+          return;
+        }
+
+        if (subCommand === "show") {
+          await emit(await mod.templatesHandler.show({ name: args[2] }));
+          return;
+        }
+
+        await emit(mod.templatesHandler.usage());
+        return;
+      }
+
       case "integrity:pin": {
-        const mod = buildCiGovernance(rootDir, harnessRoot);
+        const mod = buildCiGovernance(rootDir, harnessRoot, toCiGovernanceDocPaths(resolvedConfig));
         const dryRun = hasFlag(args, "--dry-run");
         const format = json ? "json" : "human";
         const result = await mod.integrityHandler.pin({ dryRun, format });
@@ -3362,7 +3452,7 @@ Examples:
       }
 
       case "integrity:verify": {
-        const mod = buildCiGovernance(rootDir, harnessRoot);
+        const mod = buildCiGovernance(rootDir, harnessRoot, toCiGovernanceDocPaths(resolvedConfig));
         const format = json ? "json" : "human";
         const result = await mod.integrityHandler.verify({ format });
         console.log(result.output);

package/scripts/harness/phase-dependency-model/application/services/evidence-bundle-assembler.ts

@@ -1,6 +1,7 @@
 /**
  * @layer application
  * @unit phase-dependency-model
+ * @work-item-id WI-369
  */
 
 import type { ArtifactExistenceCheckerPort } from '../../domain/ports/artifact-existence-checker-port.js';
@@ -68,7 +69,7 @@ export class EvidenceBundleAssembler {
         continue;
       }
 
-      const actual = await this.planDocumentReader.readEvidence(node, scope, planningMode);
+      const actual = await this.planDocumentReader.readEvidence(node, scope, planningMode, pathRoots);
       planEvidences.set(node.nodeKey(), actual);
     }
 

package/scripts/harness/phase-dependency-model/domain/ports/plan-document-reader-port.ts

@@ -1,16 +1,28 @@
 /**
  * @layer domain
  * @unit phase-dependency-model
+ * @work-item-id WI-369
  */
 
+import type { PathRoots } from '../values/artifact.js';
 import type { PhaseNode } from '../values/phase-node.js';
 import type { PlanEvidence } from '../values/plan-evidence.js';
 import type { PlanningMode } from '../values/planning-mode.js';
 
 export interface PlanDocumentReaderPort {
+  /**
+   * plan 文書の存在と QA evidence を読む。
+   *
+   * `pathRoots` は `phasegate.config.json` の `paths` を解決したもの。
+   * 省略時は既定ルート（`docs/inception` / `docs/product/construction`）を使う。
+   * WI-369: これを渡さないと `paths.inceptionDocs` を移設した PJ で
+   * plan 文書だけが既定パスから探され、成果物検査と plan evidence の
+   * 探索先がズレる（成果物は在るのに「plan文書が不足」で落ちる）。
+   */
   readEvidence(
     node: PhaseNode,
     scope: { unitId?: string; storyId?: string },
     expectedMode: PlanningMode,
+    pathRoots?: PathRoots,
   ): Promise<PlanEvidence>;
 }

package/scripts/harness/phase-dependency-model/infrastructure/filesystem/markdown-plan-document-reader.ts

@@ -1,11 +1,13 @@
 /**
  * @layer infrastructure
  * @unit phase-dependency-model
+ * @work-item-id WI-369
  */
 
 import { readFile } from "node:fs/promises";
 import * as path from "node:path";
 import type { PlanDocumentReaderPort } from "../../domain/ports/plan-document-reader-port.js";
+import { DEFAULT_PATH_ROOTS, type PathRoots } from "../../domain/values/artifact.js";
 import type { PhaseNode } from "../../domain/values/phase-node.js";
 import { PlanEvidence } from "../../domain/values/plan-evidence.js";
 import type { PlanningMode } from "../../domain/values/planning-mode.js";
@@ -41,6 +43,7 @@ export class MarkdownPlanDocumentReader implements PlanDocumentReaderPort {
     node: PhaseNode,
     scope: { unitId?: string; storyId?: string },
     expectedMode: PlanningMode,
+    pathRoots: PathRoots = DEFAULT_PATH_ROOTS,
   ): Promise<PlanEvidence> {
     const planArtifacts = node.planArtifacts();
 
@@ -55,7 +58,7 @@ export class MarkdownPlanDocumentReader implements PlanDocumentReaderPort {
     const artifact = planArtifacts[0];
     let resolvedPath: string;
     try {
-      resolvedPath = artifact.resolve(scope);
+      resolvedPath = artifact.resolve(scope, pathRoots);
     } catch {
       return PlanEvidence.create({
         exists: false,

package/scripts/harness/quick-mode/domain/errors/quick-mode-config-error.ts

@@ -0,0 +1,19 @@
+/**
+ * @layer domain
+ * @unit quick-mode
+ * @work-item-id WI-372
+ *
+ * QuickMode 設定の不変条件違反を表すエラー。
+ *
+ * `quick-mode-config.ts` と `category-override-rules.ts` の双方から参照されるため、
+ * 循環 import を避ける目的で独立ファイルに切り出している。
+ * 後方互換のため `quick-mode-config.ts` からも re-export される。
+ */
+
+export class QuickModeConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'QuickModeConfigError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/scripts/harness/quick-mode/domain/services/quick-mode-judgment-engine.ts

@@ -4,10 +4,12 @@
  * @work-item-id WI-204
  * @work-item-id WI-349
  * @work-item-id WI-352
+ * @work-item-id WI-372
  *
  * ChangedFile[]をChangeClassificationに変換し、3拒否ルールを評価してQuickModeEligibilityを返すドメインサービス
  */
 
+import { CategoryOverrideRules } from "../value-objects/category-override-rules.js";
 import { ChangeCategory } from "../value-objects/change-category.js";
 import { ChangeClassification } from "../value-objects/change-classification.js";
 import type { ChangedFile } from "../value-objects/changed-file.js";
@@ -15,17 +17,6 @@ import type { QuickModeConfig } from "../value-objects/quick-mode-config.js";
 import { QuickModeEligibility } from "../value-objects/quick-mode-eligibility.js";
 import { isCommentOnlyDiff } from "./comment-only-diff-detector.js";
 
-// リスク順優先度（api > domain > feature > bugfix > test > config > docs）
-const RISK_PRIORITY: Record<string, number> = {
-  api: 6,
-  domain: 5,
-  feature: 4,
-  bugfix: 3,
-  test: 2,
-  config: 1,
-  docs: 0,
-};
-
 // config: リポジトリ直下の bootstrap 設定ファイル（列挙型 allowlist）。
 // これらは unit を持たず、CREATE だと feature に落ちて allowedCategories に
 // 入れる手段がないため greenfield な初期セットアップが恒久的にブロックされていた。
@@ -57,7 +48,7 @@ function isRootBootstrapConfigFile(filePath: string): boolean {
   return filePath.startsWith(HUSKY_DIRECTORY_PREFIX) && filePath.slice(HUSKY_DIRECTORY_PREFIX.length).length > 0;
 }
 
-function categorizeFile(file: ChangedFile): ChangeCategory {
+function categorizeFileByBuiltInRules(file: ChangedFile): ChangeCategory {
   const { filePath, changeKind } = file;
 
   // Config files must stay config even when Edit payload snippets look like
@@ -130,6 +121,43 @@ function categorizeFile(file: ChangedFile): ChangeCategory {
   return ChangeCategory.fromString("bugfix");
 }
 
+// 組み込み判定が構造的に高リスク（domain / api）のカテゴリは override で降格できない。
+// @work-item-id WI-372
+const NON_DOWNGRADABLE_BUILT_IN_CATEGORIES: ReadonlySet<string> = new Set(["domain", "api"]);
+
+/**
+ * WI-372: `quickMode.categoryOverrides` を反映したカテゴリ判定。
+ *
+ * override は「このパスはこの種類の変更である」という利用者の明示宣言なので、
+ * 組み込みルールより **先** に評価する（DD-1）。組み込みの後段に置くと
+ * `notes/x.config.json` のような偶発的な組み込みマッチに常に負け、
+ * 「設定したのに効かない」不可解な挙動になるため。
+ *
+ * ただし組み込み判定が `domain` / `api` のファイルは override で降格できない（DD-2）。
+ * `judge()` の NEW_DOMAIN は CREATE のみ、API_CONTRACT は port/adapter のみを見るため、
+ * ガードが無いと domain ファイルの MODIFY が `docs` として素通りしてしまう。
+ * 降格は禁じるが昇格（domain → api 等）は許す。
+ *
+ * override 未設定時は組み込み分類と完全に一致する（後方互換）。
+ */
+function categorizeFile(file: ChangedFile, overrides: CategoryOverrideRules): ChangeCategory {
+  const builtIn = categorizeFileByBuiltInRules(file);
+  if (overrides.isEmpty()) {
+    return builtIn;
+  }
+
+  const override = overrides.resolve(file.filePath);
+  if (override === null) {
+    return builtIn;
+  }
+
+  if (NON_DOWNGRADABLE_BUILT_IN_CATEGORIES.has(builtIn.toString())) {
+    return override.riskPriority() > builtIn.riskPriority() ? override : builtIn;
+  }
+
+  return override;
+}
+
 /**
  * WI-349: 遮断理由に判定根拠（分類カテゴリと変更種別）を含める。
  *
@@ -142,17 +170,18 @@ function describeChangedFile(file: ChangedFile, category: string): string {
 }
 
 export class QuickModeJudgmentEngine {
-  classify(changedFiles: readonly ChangedFile[], _config?: QuickModeConfig): ChangeClassification {
+  classify(changedFiles: readonly ChangedFile[], config?: QuickModeConfig): ChangeClassification {
     if (changedFiles.length === 0) {
       return new ChangeClassification(null, new Map(), 0);
     }
 
+    const overrides = config?.categoryOverrides ?? CategoryOverrideRules.empty();
     const categorizedMap = new Map<string, ChangedFile[]>();
     let dominantCategory: ChangeCategory | null = null;
     let dominantPriority = -1;
 
     for (const file of changedFiles) {
-      const category = categorizeFile(file);
+      const category = categorizeFile(file, overrides);
       const key = category.toString();
 
       if (!categorizedMap.has(key)) {
@@ -160,7 +189,7 @@ export class QuickModeJudgmentEngine {
       }
       categorizedMap.get(key)!.push(file);
 
-      const priority = RISK_PRIORITY[key] ?? 0;
+      const priority = category.riskPriority();
       if (priority > dominantPriority) {
         dominantPriority = priority;
         dominantCategory = category;
@@ -206,7 +235,7 @@ export class QuickModeJudgmentEngine {
           "NEW_DOMAIN",
           newDomainFiles,
           `domain/配下に新規ファイルが追加されています: ${newDomainFiles
-            .map((f) => describeChangedFile(f, categorizeFile(f).toString()))
+            .map((f) => describeChangedFile(f, categorizeFile(f, config.categoryOverrides).toString()))
             .join(", ")}`,
         );
       }
@@ -223,7 +252,7 @@ export class QuickModeJudgmentEngine {
           "API_CONTRACT",
           apiContractFiles,
           `Port/Adapterインターフェースファイルの変更が含まれています: ${apiContractFiles
-            .map((f) => describeChangedFile(f, categorizeFile(f).toString()))
+            .map((f) => describeChangedFile(f, categorizeFile(f, config.categoryOverrides).toString()))
             .join(", ")}`,
         );
       }