phasegate 0.145.4 → 0.147.0

package/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.147.0] - 2026-05-12
+
+### Added
+
+- **WI-144 — install/uninstall idempotency umbrella closure** — publish-ready rollup for the installation lifecycle work delivered across WI-145〜WI-148.
+  - Documents the complete lifecycle commands (`install`, `doctor`, `uninstall`, `reconcile`) in README / README.ja / guide docs.
+  - Marks the WI-144 umbrella as tested after the manifest, doctor, structured install, clean uninstall, reconcile, and init deprecation slices reached tested status.
+
 ## [0.145.4] - 2026-05-11
 
 ### Added

package/README.ja.md

@@ -18,7 +18,7 @@ Claude Code / Codex / Cursor / Copilot — どの AI agent でも設計意図・
 2. **コミット前に L1〜L3 のバリデーションが自動で走り**、レイヤー違反・テスト品質違反・依存方向違反を弾く
 3. **ブロック時のエラーは AI が読んで自己修正できる形式**（理由・必要な設計文書・次に打つべきスキル名が出る）
 
-`npx phasegate init` を 1 回打てば、上記が全部入ります。
+既存プロジェクトには `npx phasegate install` で既存 hooks / scripts を壊さずに組み込み、新規プロジェクトの legacy bootstrap には `npx phasegate init` を使います。導入後は `phasegate doctor` / `uninstall` / `reconcile` で状態確認・削除・アップグレード追従ができます。
 
 ---
 
@@ -77,7 +77,7 @@ claude
 > /product-architect
 ```
 
-`init` が生成するもの:
+`init` は初期 bootstrap として以下を生成します:
 
 - `phasegate.config.json` — 品質設定の Single Source of Truth
 - `skills/` — 28 の AIDLC スキル一式
@@ -95,7 +95,7 @@ claude
 - `docs/product/` 配下の確定設計文書 — `/domain-designer` `/logical-designer` 等が生成
 - `docs/ADR/` — `/skill-creator` や手動で必要に応じて作成
 
-「設計してから書け」を強制する仕組みなので、設計文書はユーザーがスキル経由で作るのが既定動作です。
+`init` は legacy 互換の bootstrap 経路です。既存 hooks / scripts / package metadata に構造化 merge したい場合は `install` を使います。「設計してから書け」を強制する仕組みなので、設計文書はユーザーがスキル経由で作るのが既定動作です。
 
 既存プロジェクトに導入する場合は、構造化 install で差分を確認してから適用します。
 
@@ -138,9 +138,12 @@ codex features enable codex_hooks   # Codex 本体の feature flag を手動で
 
 ```bash
 npm update phasegate
-npx phasegate update-skills   # スキルを最新版に再デプロイ
+npx phasegate reconcile --dry-run
+npx phasegate reconcile --apply
 ```
 
+`update-skills` は互換 alias として残っていますが、推奨は `reconcile` です。`.phasegate/manifest.json` に記録された PhaseGate 管理ファイル全体を最新版 template に追従できます。
+
 ---
 
 ## 主な機能
@@ -312,8 +315,12 @@ npx phasegate <command> [options]
 
 | コマンド | 説明 |
 |---|---|
-| `init --name <name>` | 初期化（skills/config/hooks 配置）。`--agent claude\|codex\|both`、`--with-husky`、`--with-ci`、`--preset <full\|standard\|minimal\|custom>` |
-| `update-skills` | スキルを最新版に再デプロイ |
+| `init --name <name>` | 新規プロジェクト向け legacy bootstrap（skills/config/hooks 配置）。既存 hooks/scripts/CI がある場合は `install` を推奨 |
+| `install --dry-run` / `--apply` | 既存設定を保持しながら PhaseGate を構造化 merge し、`.phasegate/manifest.json` を作成 |
+| `doctor` | silent / partial installation を診断し、修復 hint を表示（`--json`, `--strict`, `--report-out <path>`） |
+| `uninstall --dry-run` / `--apply` | manifest に基づいて PhaseGate 管理ファイル・管理 block を削除し、ユーザー設定は保持 |
+| `reconcile --dry-run` / `--apply` | 現在の package template に PhaseGate 管理ファイルを追従し、manifest hash を更新 |
+| `update-skills` | `reconcile` の互換 alias |
 | `lint` | L1 Biome AST チェック |
 | `validate --layer <L1\|L2\|L3\|L4\|all>` | 指定レイヤーのバリデータ実行（`--format human\|agent\|ci`） |
 | `ci-check` | CI フルチェック（L2-L4）。`--quick` で Quick Mode |

package/README.md

@@ -19,7 +19,7 @@ Phasegate adds project-local hooks, validators, and agent skills that keep gener
 2. **Before commit and CI, validators check layer boundaries, metadata, test quality, security, performance, and traceability.**
 3. **Every failure is returned in an agent-readable format** with the reason, missing artifacts, references, and the next skill or command to run.
 
-Run `npx phasegate init` once and the project gets the guardrails, skills, and configuration needed to make that flow repeatable.
+Run `npx phasegate install` to merge those guardrails into an existing project, or `npx phasegate init` for the legacy bootstrap path on a new project. `phasegate doctor`, `uninstall`, and `reconcile` keep the installation observable, removable, and upgradeable.
 
 ---
 
@@ -78,7 +78,7 @@ claude
 > /product-architect
 ```
 
-`init` creates:
+`init` creates the initial project-local harness files:
 
 - `phasegate.config.json` as the quality settings source of truth
 - `skills/` with 28 AIDLC skills
@@ -88,7 +88,7 @@ claude
 - `.husky/pre-commit`, `.husky/commit-msg`, and `.husky/pre-push` when `--with-husky` is passed
 - `.github/workflows/aidlc-gate.yml`, `.github/workflows/consistency-check.yml`, and `.github/workflows/agent-context-refresh.yml` when `--with-ci` is passed
 
-`init` intentionally does **not** create `docs/inception/` work item directories or `docs/product/` design documents. Those are produced later by skills such as `/product-architect`, `/domain-designer`, and `/logical-designer`. That is the core contract: no design, no code.
+`init` is the legacy-compatible bootstrap path. For idempotent setup with structured merge into existing hooks, scripts, and package metadata, use `install`. `init` intentionally does **not** create `docs/inception/` work item directories or `docs/product/` design documents. Those are produced later by skills such as `/product-architect`, `/domain-designer`, and `/logical-designer`. That is the core contract: no design, no code.
 
 For an existing project, preview and apply a structured install instead:
 
@@ -131,9 +131,12 @@ Use `--agent both` for projects that use Claude Code and Codex together. Codex n
 
 ```bash
 npm update phasegate
-npx phasegate update-skills
+npx phasegate reconcile --dry-run
+npx phasegate reconcile --apply
 ```
 
+`update-skills` remains available as a compatibility alias, but `reconcile` is the preferred upgrade path because it updates all PhaseGate-managed files recorded in `.phasegate/manifest.json`, not just skills.
+
 ---
 
 ## Core Capabilities
@@ -494,7 +497,11 @@ npx phasegate <command> [options]
 
 | Command | Description |
 |---|---|
-| `init --name <name>` | Initialize project, deploy skills, generate config. Use `--with-ci` to deploy GitHub Actions workflows. |
+| `init --name <name>` | Legacy-compatible bootstrap for new projects: deploy skills, generate config, and optionally add hooks/CI. Prefer `install` when the project may already have hooks, scripts, or CI files. |
+| `install --dry-run` / `--apply` | Idempotently merge PhaseGate into the current project, preserve existing user content, add package scripts/devDependency, and write `.phasegate/manifest.json`. |
+| `doctor` | Diagnose silent or partial installations and report repair hints (`--json`, `--strict`, `--report-out <path>`). |
+| `uninstall --dry-run` / `--apply` | Remove PhaseGate-managed files and managed blocks using `.phasegate/manifest.json`, preserving user content. |
+| `reconcile --dry-run` / `--apply` | Update PhaseGate-managed files to the current package templates and refresh manifest hashes. |
 | `lint` | Run L1 Biome AST checks |
 | `validate --layer <L1-L4\|all>` | Run validators for specified layer (`--layer L0` prints runtime hook guidance; explicit L4 runs even when scheduled L4 is disabled) |
 | `ci-check` | Full CI check (L2-L4; disabled L4 is reported as skipped) |
@@ -502,7 +509,7 @@ npx phasegate <command> [options]
 | `ci:auto-refresh-agent-context --dry-run` / `--apply` | Refresh AGENTS.md pointers and CLAUDE.md standard sections |
 | `refresh-claude-md --dry-run` / `--apply` | Refresh only CLAUDE.md while preserving the user-owned section |
 | `p2:check-agent-context` | Check AGENTS.md / CLAUDE.md freshness |
-| `update-skills` | Update skills to latest version |
+| `update-skills` | Compatibility alias for `reconcile` |
 | `phasegate:status` | Display overall harness health summary |
 | `work-items:status --dry-run` / `--apply` | Derive WI status from artifacts and optionally update stale `description.md` frontmatter. Apply refuses downgrades unless `--allow-downgrade` is supplied. |
 | `phasegate:check-phase --unit <id>` | Check current phase for a Unit |

package/docs/guide/cli-reference.md

@@ -12,8 +12,12 @@ npx phasegate <command> [options]
 
 | Command | Description |
 |---|---|
-| `init --name <name>` | Deploy skills and generate `phasegate.config.json` |
-| `update-skills` | Re-deploy skills to the latest version |
+| `init --name <name>` | Legacy-compatible bootstrap for new projects: deploy skills, generate config, and optionally add hooks/CI |
+| `install --dry-run` / `--apply` | Idempotently merge PhaseGate into an existing project, preserve user content, add package scripts/devDependency, and write `.phasegate/manifest.json` |
+| `doctor` | Diagnose silent or partial installations and report repair hints (`--json`, `--strict`, `--report-out <path>`) |
+| `uninstall --dry-run` / `--apply` | Remove PhaseGate-managed files and managed blocks using `.phasegate/manifest.json` |
+| `reconcile --dry-run` / `--apply` | Update PhaseGate-managed files to current package templates and refresh manifest hashes |
+| `update-skills` | Compatibility alias for `reconcile` |
 | `list-features` | List available features |
 | `enable-feature <name>` | Enable a feature |
 | `disable-feature <name>` | Disable a feature |

package/docs/guide/installation.md

@@ -6,7 +6,7 @@
 - **npm** 9+ or **pnpm**
 - **TypeScript** 5.x (included as a devDependency)
 
-## Install from GitHub
+## Install from npm
 
 ```bash
 npm install --save-dev phasegate
@@ -17,7 +17,7 @@ Or add it directly to your `package.json`:
 ```json
 {
   "devDependencies": {
-    "phasegate": "^0.145.3"
+    "phasegate": "^0.147.0"
   }
 }
 ```
@@ -38,6 +38,8 @@ npx phasegate init --name <project-name>
 
 This deploys 28 skills to `skills/`, creates the agent-facing skill links (for example `.claude/skills/` or `.codex/skills/`), and generates `phasegate.config.json`.
 
+`init` is the legacy-compatible bootstrap path for new projects. Use `install` when the project may already have hooks, package scripts, or CI files that should be preserved.
+
 For Codex, project initialization stops at the project boundary. After `npx phasegate init --agent codex`, enable the Codex CLI feature flag manually:
 
 ```bash
@@ -82,8 +84,6 @@ npx phasegate reconcile --apply
 
 `reconcile` updates PhaseGate-managed portions, preserves user content, adds newly introduced managed targets, and refreshes `.phasegate/manifest.json` with current version/hash metadata. If a managed file was edited after install, `reconcile --apply` refuses that entry until you rerun with `--force`, which creates a backup under `.phasegate/backups/reconcile-<timestamp>/`.
 
-`phasegate update-skills` remains available as a compatibility alias for `phasegate reconcile`.
-
 ### Manual Setup Pieces
 
 If you do not use `init` or `install`, copy the design principle documents manually:
@@ -110,9 +110,12 @@ Run `/product-architect` to begin the AIDLC process.
 
 ```bash
 npm update phasegate
-npx phasegate update-skills
+npx phasegate reconcile --dry-run
+npx phasegate reconcile --apply
 ```
 
+`phasegate update-skills` remains available as a compatibility alias, but `reconcile` is the preferred upgrade path because it updates all managed files recorded in `.phasegate/manifest.json`.
+
 ## Recommended .gitignore additions
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.145.4",
+  "version": "0.147.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",

package/scripts/harness/biome-ast-engine/infrastructure/adapters/typescript-source-module-analyzer-adapter.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit biome-ast-engine
+ * @work-item-id WI-109
  */
 
 import * as ts from 'typescript';

package/scripts/harness/harness-api/domain/services/command-dispatch-service.ts

@@ -1,5 +1,6 @@
 // @layer domain
 // @unit harness-api
+// @work-item-id WI-108
 // command-dispatch-service.ts — CommandDispatchService Domain Service
 
 import { CommandRegistry } from './command-registry.js';

package/scripts/harness/installation/application/checks/wi-workflow-drift-check.ts

@@ -0,0 +1,64 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-143
+
+import { join, relative, sep } from "node:path";
+import { DiagnosticFinding } from "../../domain/diagnostic-finding.js";
+import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
+import type { FileInspectorPort } from "../ports/file-inspector-port.js";
+
+interface PhasegateConfigProbe {
+  readonly quickMode?: {
+    readonly relaxedGates?: readonly string[];
+  };
+}
+
+export class WiWorkflowDriftCheck implements HeuristicCheck {
+  readonly checkId = "wi-workflow-drift" as const;
+
+  async run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
+    const inceptionRoot = join(projectRoot, "docs", "inception");
+    const files = await inspector.listFiles(inceptionRoot);
+    const relativeFiles = files.map((file) => toPosix(relative(projectRoot, file)));
+    const workItemCount = relativeFiles.filter(isWorkItemDescription).length;
+    const adHocPlans = relativeFiles.filter(isAdHocPlan);
+    const hasPhaseGateRelaxed = await this.hasRelaxedPhaseGate(projectRoot, inspector);
+
+    if (workItemCount > 0 || adHocPlans.length === 0) {
+      return null;
+    }
+
+    const message = hasPhaseGateRelaxed
+      ? `WI-first drift detected: 0 WI directories, ${adHocPlans.length} ad-hoc plan file(s), and quickMode.relaxedGates includes phase-gate.`
+      : `WI-first drift detected: 0 WI directories and ${adHocPlans.length} ad-hoc plan file(s).`;
+
+    return DiagnosticFinding.create({
+      checkId: this.checkId,
+      severity: "red",
+      target: "docs/inception",
+      message,
+      repairMode: "mechanical",
+      repairHint: "phasegate migrate work-items --apply",
+      suggestedSkill: null,
+    });
+  }
+
+  private async hasRelaxedPhaseGate(projectRoot: string, inspector: FileInspectorPort): Promise<boolean> {
+    const config = await inspector.readJson<PhasegateConfigProbe>(join(projectRoot, "phasegate.config.json"));
+    return config?.quickMode?.relaxedGates?.includes("phase-gate") ?? false;
+  }
+}
+
+function toPosix(path: string): string {
+  return path.split(sep).join("/");
+}
+
+function isWorkItemDescription(path: string): boolean {
+  return /^docs\/inception\/(?:_cross|[^/]+)\/WI-\d{3}\/description\.md$/.test(path);
+}
+
+function isAdHocPlan(path: string): boolean {
+  if (!path.startsWith("docs/inception/")) return false;
+  if (/\/WI-\d{3}\//.test(path)) return false;
+  return path.includes("/codding_plan/") || path.endsWith("_plan.md");
+}

package/scripts/harness/installation/composition-root.ts

@@ -12,6 +12,7 @@ import { HuskyCommitMsgMissingCheck } from "./application/checks/husky-commit-ms
 import { HuskyPreCommitMissingCheck } from "./application/checks/husky-pre-commit-missing-check.js";
 import { HuskyPrePushMissingCheck } from "./application/checks/husky-pre-push-missing-check.js";
 import { PackageJsonDevdepMissingCheck } from "./application/checks/package-json-devdep-missing-check.js";
+import { WiWorkflowDriftCheck } from "./application/checks/wi-workflow-drift-check.js";
 import { RunInstallUseCase } from "./application/usecases/run-install.js";
 import { RunReconcileUseCase } from "./application/usecases/run-reconcile.js";
 import { RunUninstallUseCase } from "./application/usecases/run-uninstall.js";
@@ -49,6 +50,7 @@ export function createInstallationModule() {
     new PackageJsonDevdepMissingCheck(),
     new ClaudeSkillsSymlinkCheck(),
     new CodexSkillsSymlinkCheck(),
+    new WiWorkflowDriftCheck(),
   ];
   const runDoctorDiagnosticsUseCase = new RunDoctorDiagnosticsUseCase(checks, inspector, manifestRepository);
   const runInstallUseCase = new RunInstallUseCase(manifestRepository, hashCalculator);

package/scripts/harness/installation/domain/check-id.ts

@@ -12,6 +12,7 @@ export const CHECK_IDS = [
   "package-json-devdep-missing",
   "claude-skills-symlink",
   "codex-skills-symlink",
+  "wi-workflow-drift",
 ] as const;
 
 export type CheckId = (typeof CHECK_IDS)[number];

package/scripts/harness/installation/infrastructure/adapters/node-fs-file-inspector-adapter.ts

@@ -45,7 +45,16 @@ export class NodeFsFileInspectorAdapter implements FileInspectorPort {
   async listFiles(absolutePath: string): Promise<string[]> {
     try {
       const entries = await readdir(absolutePath, { withFileTypes: true });
-      return entries.filter((entry) => entry.isFile()).map((entry) => join(absolutePath, entry.name));
+      const files: string[] = [];
+      for (const entry of entries) {
+        const entryPath = join(absolutePath, entry.name);
+        if (entry.isFile()) {
+          files.push(entryPath);
+        } else if (entry.isDirectory()) {
+          files.push(...(await this.listFiles(entryPath)));
+        }
+      }
+      return files;
     } catch {
       return [];
     }

package/scripts/harness/integrations/pre-commit.ts

@@ -2,6 +2,7 @@
  * @unit harness-api
  * @layer presentation
  * @work-item-id WI-141
+ * @work-item-id WI-109
  *
  * Pre-commit CLI entry.
  * Runs L2 validators against staged TypeScript files AND design-document

package/scripts/harness/main.ts

@@ -1,6 +1,7 @@
 /**
  * @unit harness-api
  * @layer presentation
+ * @work-item-id WI-142
  *
  * Phasegate CLI エントリポイント。
  * 各Unitの Composition Root からハンドラーを取得し、コマンドに応じてディスパッチする。
@@ -8,7 +9,13 @@
  * 起動時に config-foundation で設定を解決し、他Unit に注入する（Cross-unit wiring）。
  */
 
-import { readFile as fsReadFile, readlink as fsReadlink, writeFile as fsWriteFile } from "node:fs/promises";
+import {
+  mkdir as fsMkdir,
+  readFile as fsReadFile,
+  readdir as fsReaddir,
+  readlink as fsReadlink,
+  writeFile as fsWriteFile,
+} from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { createAdrFoundationModule } from "./adr-foundation/composition-root.js";
 import { createBiomeAstEngineModule } from "./biome-ast-engine/composition-root.js";
@@ -138,9 +145,12 @@ Usage: phasegate <command> [options]
 Setup:
   init                         Initialize project: deploy skills + design docs + phasegate.config.json
                                (--name <project-name>, --preset <full|standard|minimal|custom>,
-                                --skills <core|all>, --agent <claude|codex|both>, --with-husky, --with-ci, --yes)
+                                --skills <core|all>, --agent <claude|codex|both>, --workflow <standard|strict>,
+                                --with-husky, --with-ci, --yes)
   update-skills                Alias for reconcile (kept for compatibility)
   doctor                       Diagnose silent installation failures (--json, --strict, --report-out <path>)
+  scaffold-wi <unit> <type>    Create docs/inception/{unit}/WI-XXX/description.md
+  emit-agent-rules             Print AGENTS.md / CLAUDE.md WI workflow rules block
   install                      Install phasegate managed files (--dry-run|--apply, --force)
   uninstall                    Uninstall phasegate managed files (--dry-run|--apply, --force)
   reconcile                    Reconcile phasegate managed files (--dry-run|--apply, --force)
@@ -232,6 +242,103 @@ function hasFlag(args: readonly string[], flag: string): boolean {
   return args.includes(flag);
 }
 
+type WorkflowMode = "standard" | "strict";
+type ScaffoldWorkItemType = "story" | "issue" | "chore";
+
+function parseWorkflowMode(value: string | undefined): WorkflowMode {
+  return value === "strict" ? "strict" : "standard";
+}
+
+function parseScaffoldWorkItemType(value: string | undefined): ScaffoldWorkItemType | null {
+  if (value === "story" || value === "issue" || value === "chore") return value;
+  return null;
+}
+
+function emitAgentRulesBlock(): string {
+  return [
+    "## PhaseGate WI Workflow (auto-generated; do not edit by hand)",
+    "- All plans/designs/implementations require a WI directory first.",
+    "- Path: `docs/inception/{unit}/WI-XXX/description.md` with required frontmatter.",
+    "- Use `phasegate scaffold-wi <unit> <type>` to create one.",
+    "- Plans written under `docs/inception/codding_plan/` are legacy; new plans go in WI dirs.",
+  ].join("\n");
+}
+
+async function listFilesRecursive(root: string): Promise<string[]> {
+  try {
+    const entries = await fsReaddir(root, { withFileTypes: true });
+    const files: string[] = [];
+    for (const entry of entries) {
+      const path = join(root, entry.name);
+      if (entry.isFile()) {
+        files.push(path);
+      } else if (entry.isDirectory()) {
+        files.push(...(await listFilesRecursive(path)));
+      }
+    }
+    return files;
+  } catch {
+    return [];
+  }
+}
+
+async function nextWorkItemId(rootDir: string): Promise<string> {
+  const files = await listFilesRecursive(join(rootDir, "docs", "inception"));
+  let max = 0;
+  for (const file of files) {
+    const match = file.match(/\/WI-(\d{3})\/description\.md$/);
+    if (match) max = Math.max(max, Number(match[1]));
+  }
+  return `WI-${String(max + 1).padStart(3, "0")}`;
+}
+
+async function countLegacyPlansWithoutWorkItems(rootDir: string): Promise<number> {
+  const files = await listFilesRecursive(join(rootDir, "docs", "inception"));
+  const hasWorkItem = files.some((file) => /\/WI-\d{3}\/description\.md$/.test(file));
+  if (hasWorkItem) return 0;
+  return files.filter((file) => file.includes("/codding_plan/") || file.endsWith("_plan.md")).length;
+}
+
+async function scaffoldInceptionRoots(rootDir: string, unit: string | null = null): Promise<void> {
+  await fsMkdir(join(rootDir, "docs", "inception", "_shared"), { recursive: true });
+  await fsMkdir(join(rootDir, "docs", "inception", "_cross"), { recursive: true });
+  if (unit && unit !== "_cross" && unit !== "_shared") {
+    await fsMkdir(join(rootDir, "docs", "inception", unit), { recursive: true });
+    await fsWriteFile(join(rootDir, "docs", "inception", unit, ".gitkeep"), "", "utf8").catch(() => undefined);
+  }
+}
+
+async function scaffoldWorkItem(rootDir: string, unit: string, type: ScaffoldWorkItemType): Promise<string> {
+  const id = await nextWorkItemId(rootDir);
+  await scaffoldInceptionRoots(rootDir, unit);
+  const targetBase = unit === "_cross" ? join(rootDir, "docs", "inception", "_cross") : join(rootDir, "docs", "inception", unit);
+  const targetDir = join(targetBase, id);
+  await fsMkdir(targetDir, { recursive: true });
+  const descriptionPath = join(targetDir, "description.md");
+  const titleScope = unit === "_cross" ? "Cross-cutting" : unit;
+  const content = [
+    "---",
+    `id: ${id}`,
+    `type: ${type}`,
+    "severity: normal",
+    "status: drafted",
+    "---",
+    "",
+    `# ${id}: ${titleScope} work item`,
+    "",
+    "## Context",
+    "",
+    "TBD",
+    "",
+    "## Acceptance Criteria",
+    "",
+    "- [ ] TBD",
+    "",
+  ].join("\n");
+  await fsWriteFile(descriptionPath, content, "utf8");
+  return descriptionPath;
+}
+
 async function createFileManifestRecord(
   rootDir: string,
   relativePath: string,
@@ -349,6 +456,7 @@ Options:
   --preset <full|standard|minimal|custom>   Phase dependency preset (default: "standard")
   --skills <core|all>             Skill set to deploy (default: "all")
   --agent <claude|codex|both>     Agent integration target (default: "claude")
+  --workflow <standard|strict>    Workflow enforcement defaults (default: "standard")
   --with-husky                    Install Husky pre-commit hooks
   --with-ci                       Install GitHub Actions workflows
   --yes                           Skip confirmation prompts
@@ -777,7 +885,16 @@ async function main(): Promise<void> {
         console.log("Warning: phasegate init is deprecated and will be removed in v1.0.");
         console.log("Use phasegate install for idempotent setup with structured merge.");
         console.log("Existing legacy init behavior is preserved. Run phasegate doctor to verify installation state.");
-        const KNOWN_INIT_FLAGS = ["--name", "--preset", "--skills", "--agent", "--with-husky", "--with-ci", "--yes"];
+        const KNOWN_INIT_FLAGS = [
+          "--name",
+          "--preset",
+          "--skills",
+          "--agent",
+          "--workflow",
+          "--with-husky",
+          "--with-ci",
+          "--yes",
+        ];
         const flagError = validateKnownFlags(args, KNOWN_INIT_FLAGS);
         if (flagError) {
           console.error(flagError);
@@ -808,6 +925,12 @@ async function main(): Promise<void> {
           process.exit(2);
         }
         const agent = agentRaw;
+        const workflowRaw = parseFlag(args, "--workflow");
+        if (workflowRaw !== undefined && workflowRaw !== "standard" && workflowRaw !== "strict") {
+          console.error(`Invalid --workflow value: "${workflowRaw}". Use "standard" or "strict".`);
+          process.exit(2);
+        }
+        const workflow = parseWorkflowMode(workflowRaw);
         const deployClaude = agent === "claude" || agent === "both";
         const deployCodex = agent === "codex" || agent === "both";
         const result = await deploySkills(harnessRoot, rootDir, skillSet);
@@ -817,7 +940,13 @@ async function main(): Promise<void> {
           codex: deployCodex,
         });
         const withCi = hasFlag(args, "--with-ci");
-        const configResult = await initHarnessConfig(rootDir, projectName, phasePreset, { ciEnabled: withCi });
+        const configResult = await initHarnessConfig(rootDir, projectName, phasePreset, {
+          ciEnabled: withCi,
+          workflow,
+        });
+        if (workflow === "strict") {
+          await scaffoldInceptionRoots(rootDir);
+        }
         const hooksResult = deployClaude
           ? await deployHookScripts(harnessRoot, rootDir)
           : {
@@ -891,6 +1020,9 @@ async function main(): Promise<void> {
         }
         if (configResult.created) {
           console.log(`✓ phasegate.config.json created`);
+          if (workflow === "strict") {
+            console.log(`✓ strict workflow configured (quickMode.relaxedGates: [], allowedCategories: ["chore"])`);
+          }
         } else {
           console.log(`  phasegate.config.json already exists, skipped`);
         }
@@ -966,6 +1098,13 @@ async function main(): Promise<void> {
           }
         }
         console.log(`✓ Harness v${result.version} initialized (agent: ${agent})`);
+        const legacyPlanCount = await countLegacyPlansWithoutWorkItems(rootDir);
+        if (legacyPlanCount > 0) {
+          console.log("");
+          console.log(`Detected ${legacyPlanCount} legacy plan file(s) with no WI directories.`);
+          console.log("Run migration? [Y/n]");
+          console.log("  phasegate migrate work-items --apply");
+        }
         console.log("");
         console.log("Next steps:");
         if (skillSet === "core") {
@@ -1035,6 +1174,25 @@ async function main(): Promise<void> {
         break;
       }
 
+      case "emit-agent-rules": {
+        console.log(emitAgentRulesBlock());
+        process.exit(0);
+        break;
+      }
+
+      case "scaffold-wi": {
+        const unit = args[1];
+        const type = parseScaffoldWorkItemType(args[2]);
+        if (!unit || !type) {
+          console.error("Usage: phasegate scaffold-wi <unit|_cross> <story|issue|chore>");
+          process.exit(2);
+        }
+        const descriptionPath = await scaffoldWorkItem(rootDir, unit, type);
+        console.log(`Created ${descriptionPath}`);
+        process.exit(0);
+        break;
+      }
+
       case "install": {
         const KNOWN_INSTALL_FLAGS = ["--dry-run", "--apply", "--force", "--json"];
         const flagError = validateKnownFlags(args, KNOWN_INSTALL_FLAGS);

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

@@ -422,6 +422,7 @@ export async function deployHookScripts(harnessRoot: string, projectRoot: string
 
 export interface InitHarnessConfigOptions {
   ciEnabled?: boolean;
+  workflow?: "standard" | "strict";
 }
 
 export async function initHarnessConfig(
@@ -438,6 +439,7 @@ export async function initHarnessConfig(
     // ファイルが存在しない場合はテンプレートを作成
   }
 
+  const strictWorkflow = options.workflow === "strict";
   const template = {
     project: {
       name: projectName,
@@ -447,7 +449,12 @@ export async function initHarnessConfig(
       preset: "clean",
     },
     layers: {},
-    quickMode: {},
+    quickMode: strictWorkflow
+      ? {
+          allowedCategories: ["chore"],
+          relaxedGates: [],
+        }
+      : {},
     phaseDependencies: {
       preset: phasePreset ?? "default",
       override: false,

package/scripts/harness/validator-system/application/use-cases/run-l4-validators-usecase.ts

@@ -1,6 +1,7 @@
 /**
  * @layer application
  * @unit validator-system
+ * @work-item-id WI-107
  *
  * RunL4ValidatorsUseCase — H08-03: L4バリデータ実行
  */

package/skills/implementation-planner/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: implementation-planner
-description: "Unit仕様とドメインモデル設計を元に実装計画を立てる。ストーリーIDや機能名から関連Unitを特定し、API設計・レイヤー別実装方針を整理してmdファイルで出力する。使用タイミング: 実装計画を立てて、US-XXXの実装方針を決めて、この機能の設計を整理して、など実装前の計画策定時。"
+description: "Unit仕様とドメインモデル設計を元に実装計画を立てる。WI IDや機能名から関連Unitを特定し、API設計・レイヤー別実装方針を整理してmdファイルで出力する。使用タイミング: 実装計画を立てて、WI-XXXの実装方針を決めて、この機能の設計を整理して、など実装前の計画策定時。"
 model: sonnet
 review: opus
 ---
@@ -35,6 +35,11 @@ UnitドキュメントとConstructionのドメインモデル設計を元に、*
 
 ## ワークフロー
 
+## Pre-flight check (BLOCKING)
+
+Before generating any plan, verify `docs/inception/{unit}/WI-XXX/description.md` exists.
+If not, halt and ask the user to create the WI first, or offer to run `phasegate scaffold-wi <unit> <story|issue|chore>`.
+
 ```
 入力解析 → Unit特定 → ドメインモデル確認 → 既存実装確認 → 計画作成 → 出力
 ```
@@ -42,7 +47,7 @@ UnitドキュメントとConstructionのドメインモデル設計を元に、*
 ### Step 1: 入力解析
 
 ユーザー入力から抽出:
-- ストーリーID（US-XXX形式）
+- WI ID（WI-XXX形式）
 - 機能名・タスク説明
 - 優先度・制約条件
 
@@ -85,6 +90,7 @@ UnitドキュメントとConstructionのドメインモデル設計を元に、*
 計画をmdファイルとして出力。パスの推奨:
 ```
 docs/inception/{task_id}_plan.md
+docs/inception/{unit}/WI-XXX/tdd_implementation_plan.md
 ```
 
 **[Question][Answer]セクション必須**: 不明点や確認事項をまとめ、ユーザーからのフィードバックを受け取れるようにする。

package/skills/logical-designer/SKILL.md

@@ -18,6 +18,11 @@ Unit単位でアーキテクチャの各層（DB → ドメイン → ユース
 
 ## 前提条件チェック
 
+## Pre-flight check (BLOCKING)
+
+Before generating any plan, verify `docs/inception/{unit}/WI-XXX/description.md` exists.
+If not, halt and ask the user to create the WI first, or offer to run `phasegate scaffold-wi <unit> <story|issue|chore>`.
+
 ### 必須インプット（存在しなければ`[Question]`で提供を要求）
 
 - **横断モード:**
@@ -95,7 +100,7 @@ Unit単位でアーキテクチャの各層（DB → ドメイン → ユース
 設計方針・スコープ・不明点を整理し、人間の承認を得る。
 
 ### 出力ファイル
-`docs/inception/{unit}/logical_design_plan.md`（横断）または `docs/inception/{unit}/{story_id}/logical_design_plan.md`（ストーリー固有）
+`docs/inception/{unit}/WI-XXX/logical_design_plan.md`
 
 ### 計画ファイルの構成
 
@@ -173,7 +178,7 @@ Unit単位でアーキテクチャの各層（DB → ドメイン → ユース
 | 種別 | 配置先 |
 |------|--------|
 | 横断成果物 | `docs/product/construction/{unit}/logical_design.md` |
-| ストーリー固有成果物 | `docs/inception/{unit}/{story_id}/logical_design.md` |
+| ストーリー固有成果物 | `docs/inception/{unit}/WI-XXX/logical_design.md` |
 
 > **注意**: ストーリー固有の設計は `docs/inception/` に配置する（`docs/folder_management_rules.md` のルール準拠）。`docs/product/construction/` にはUnit全体の共有設計のみを配置する。
 
@@ -194,22 +199,22 @@ traceability:
 ---
 ```
 
-`initial_creation: true` は「新規作成であり、後述の `@story-id` 注釈が必須」であることを示す。
+`initial_creation: true` は「新規作成であり、後述の `@work-item-id` 注釈が必須」であることを示す。
 
-### 2. `@story-id` インライン注釈
+### 2. `@work-item-id` インライン注釈
 
-ユーザーストーリーに紐づく設計要素の直前に `@story-id HXX-XX` を独立行で記述する。
+WI に紐づく設計要素の直前に `@work-item-id WI-XXX` を独立行で記述する。
 
 ```markdown
-@story-id H03-02
+@work-item-id WI-001
 ### ユースケース: 注文を確定する
 ```
 
 形式ルール:
 - **独立行** — 他のテキストと混在させない
 - **直後に設計要素** — 空行を挟まない
-- **StoryCatalog 存在** — `HXX-XX` は `docs/product/user_stories.md` に存在する ID
-- **複数ストーリー時** — 注釈行を連続で並べ、最後の直後に設計要素を置く
+- **WorkItem 存在** — `WI-XXX` は `docs/inception/{unit}/WI-XXX/description.md` に存在する ID
+- **複数WI時** — 注釈行を連続で並べ、最後の直後に設計要素を置く
 
 ---
 

package/skills/story-writer/SKILL.md

@@ -11,6 +11,11 @@ review: opus
 
 ## 前提条件チェック
 
+## Pre-flight check (BLOCKING)
+
+Before generating any plan, verify `docs/inception/{unit}/WI-XXX/description.md` exists.
+If not, halt and ask the user to create the WI first, or offer to run `phasegate scaffold-wi <unit> <story|issue|chore>`.
+
 ### 必須インプット（存在しなければ`[Question]`で提供を要求）
 - **要求文書** — 何を作るかを記述した文書。形式は問わない（議事録、要件メモ、口頭要約のテキスト等）