phasegate 0.340.0 → 0.341.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.341.0] - 2026-09-20
+
+### Changed
+
+- **WI-220 — Hook and CLI runtime improvements** — Avoid unnecessary read-only/disabled hook work, preserve legacy hook settings, load CLI modules and schemas lazily, and distribute compiled runtime JavaScript through the tested runtime tarball. Improve child-process cleanup, interrupted configuration/reconcile recovery, dependency-scoped reflection diagnostics, and cascade/TDD traceability. <!-- @work-item-id WI-220 -->
+
+### Known limitations
+
+- WI-220 remains incomplete: the absolute 500ms/format-only fast-path target, full semantic impact classification, and the agent reading comparison acceptance criterion remain unmet. This release does not mark those requirements as satisfied. <!-- @work-item-id WI-220 -->
+
+## Previous unreleased notes
+
 ### Added
 
 - **WI-385 — Grok Build / Antigravity pre-edit integration** — PreToolUse now detects flat snake_case, flat camelCase, and nested `toolCall` payloads structurally, maps Grok and Antigravity write vocabularies into the existing gate, and renders runtime-specific deny JSON without changing Claude/Codex stdout contracts. Install/init/setup/doctor accept `grok`, `antigravity`, and `all` while preserving `both=claude+codex`; lifecycle management adds the Antigravity named hook map, Grok/Antigravity structural doctor checks, trust/CLI-only notices, and explicit L2 backstop guidance. <!-- @work-item-id WI-385 -->

package/docs/folder_management_rules.md

@@ -101,7 +101,16 @@ legacy_id: ISSUE-XXX | US-XXX | H{NN}-{NN}             # 任意: 移行用エイ
 source: github#123 | slack | internal                   # 任意: 外部報告源
 ---
 ```
-
+<!-- @work-item-id WI-220 -->
+
+  `depends_on` はWI間の直接依存宣言です。フェーズ設定の
+  `dependsOn` とは別の項目です。
+  - 明示的な `[]` は「依存なし」、未記載は「不明」とします。
+  - 既存WIへの一括追記は行いません。
+  - 依存情報が不正・不足している場合、部分的な依存集合だけで必要な反映検査を省きません。
+  - 依存宣言自体は、設計内容の反映や承認の証明ではありません。
+  - 既存の通常metadata検査は変更せず、依存チェックの警告／明示選択した強制化経路で追加診断します。
+  
 ### 3.3 type による要求成果物の段階化
 
 WI の重さに応じて、生成必須の成果物が変わります。

package/docs/guide/cli-reference.md

@@ -39,6 +39,8 @@ Command names in this document are split into three surfaces:
 
 ### Setup JSON and report outputs
 
+`config:plan` does not initialize or reconstruct a missing/unreadable/malformed configuration. For unreadable or malformed input, config-changing previews report `configPatch.applicability: "blocked"`. Missing input retains the legacy preview (`before: null`, `applicability: "applicable"`, partial patch), with `phasegate install --dry-run` listed first; this preview is not permission to create a partial configuration. In all three cases, `--apply` refuses with exit 1 without changing files. For damaged JSON, an authorized operator should restore a known-good copy or repair the JSON before retrying; do not repeatedly attempt protected direct writes. Valid config updates retain a byte-preserving backup. Existing schema-validation failures still exit 2. <!-- @work-item-id WI-220 -->
+
 <!-- @work-item-id WI-158 -->
 
 Setup lifecycle commands support JSON for automation where shown by help: `install --json`, `reconcile --json`, `uninstall --json`, and `doctor --json`. `doctor --agent claude --json` and `doctor --agent codex --json` include `scope` and `scopedOutFindings` so agents can distinguish selected-agent readiness from full-install diagnostics. Scoped-out findings suppress immediate repair guidance with `repairHint: null`, `suggestedSkill: null`, `currentScopeRepairTarget: false`, `repairHintApplicability: "only-if-agent-selected"`, and `repairModeApplicability: "only-if-agent-selected"`; applicable `findings[]` use `currentScopeRepairTarget: true` with applicable repair fields. `doctor --report-out <path>` persists the doctor JSON payload to that exact path. Relative paths are resolved from the project root; absolute paths are used as-is. <!-- @work-item-id WI-178, WI-179, WI-180 -->
@@ -67,6 +69,14 @@ This is separate from `reporting.outputDir`. The configured report directory is
 
 ### `check-change-category` の使い方
 
+<!-- @work-item-id WI-220 -->
+
+任意の `--risk-snapshots snapshots.json` は既存分類とは別に `riskAdvice` を追加する。入力は `[{"filePath":"src/foo.ts","beforeContent":"...","afterContent":"..."}]`（内容はstringまたはnull）。filePathは `--paths` と完全一致させる。未指定時の出力・処理は従来どおり。指定しても `fullModeRequired` と `--fail-on-full-required` の終了コードは変えない。
+
+助言は `module-surface-change`（明示されたmodule宣言の差分）、`behavior-review`（宣言不変だが本文の意味は要確認）、`unknown`（情報不足・未対応）、`no-content-change`（提供された同文snapshotのみ）のいずれか。構文比較対象は明示型付きexport関数・interface・typeと、型が明示されたclass method/property/constructor。classの本文・property初期値は宣言比較から分離する。decorator、accessor、型推論、default引数、再export、宣言ファイル、create/delete等の未対応構文は不明になる。内部adapterであることや業務上の同値性をpathだけから認定しない。
+
+snapshotは呼出元の比較資料であり、現在のファイル・上位承認との一致を検証した証拠ではない。出力のbeforeHash/afterHashで比較内容を特定し、実revisionと照合する。契約差分候補は上位契約と利用者への影響、本文変更は認可・不変条件・保存形式を確認する。不明は自動許可・追加の強制拒否のどちらにも変換しない。助言機能だけで意味リスク判定が完成したとは扱わない。
+
 ISSUE-006 Story A で導入。Quick Mode で取り扱おうとしている変更が
 `quickMode.fullModeRequiredWhen` のいずれかをトリガーするか事前に確認したいときに使う。
 
@@ -374,7 +384,7 @@ The following are binary subcommands (`npx phasegate <command>`). Do not assume
 | `phasegate:check-phase` | `--unit <unitId>` `--json` | Current phase for a unit |
 | `phasegate:ci-check` | `--json` | Full CI check (L2-L4; disabled L4 is reported as skipped) |
 | `phasegate:detect-drift` | `--json` | Design-code drift report |
-| `phasegate:lint` | `--target <path>` `--json` | Lint via harness-api |
+| `phasegate:lint` | `--target <path>` (repeatable) `--json` | Analyze the full graph; restrict reported diagnostics to targets |
 | `phasegate:complete-check` | `--json` | L2-L4 full check |
 | `phasegate:impact-analysis` | `<storyId>` `--json` | Story impact analysis |
 | `phasegate:generate-matrix` | `--requirements <path>` `--tests <path>` `--out <path>` `--json` | Generate the requirement-test matrix |
@@ -490,12 +500,18 @@ ISSUE-005 P3-10 で明確化された境界:
 
 | Command | Options | Description |
 |---|---|---|
-| `skill:execute-tdd-cycle` | `--unit` `--story` `--desc` `--phase RED\|GREEN\|REFACTOR` `--passed` | Run TDD cycle |
+| `skill:execute-tdd-cycle` | `--unit` `--story` `--desc` `--phase RED\|GREEN\|REFACTOR` `--passed` `--configured-validation` (optional) | Validate commit readiness and commit staged changes |
 | `skill:check-coverage` | `--story <storyId>` `--json` | Coverage check |
 | `skill:collect-lessons` | `--story <storyId>` `--sources <paths>` `--write-artifact` | Collect agent lessons |
-| `skill:apply-cascade-update` | `--story <storyId>` `--dry-run` | Cascade update to upstream docs |
+| `skill:apply-cascade-update` | `--story <storyId>` `--dry-run` | Append traceability tags only; does not perform semantic design review. Counts changed files (planned changes in dry-run), not already-tagged files. |
 | `skill:validate-structure` | `--file <path>` `--json` | Validate skill structure |
 
+`skill:apply-cascade-update --story WI-220` writes `@work-item-id WI-220`; legacy story IDs keep `@story-id`. Existing legacy annotations remain readable and unchanged. IDs are matched exactly, including comma/space-separated lists. Repeated target paths are processed once per invocation, including failed reads; fix the reported cause before explicitly retrying. JS/TS source annotations are comments so tagging does not invalidate source syntax. This command still performs tag updates only, not semantic design review. <!-- @work-item-id WI-220 -->
+
+`skill:execute-tdd-cycle` does not run tests: `--passed` is the caller's assertion that tests passed. Run the relevant tests first. The command requires `REFACTOR` and `--passed`, runs its validation gates, and invokes a normal Git commit without bypassing hooks. With `--story WI-220` (or another `WI-<number>`), the commit includes a `Work-Item` trailer; legacy story IDs retain their existing subject without an inferred WI mapping.
+
+By default, the TDD command preserves its legacy L1/L2/L3 validation profile, including warning-as-blocking behavior. Existing settings previously ignored by this command do not silently introduce new blockers after an upgrade. To explicitly adopt the resolved L1/architecture and L2/L3 settings, use `--configured-validation`. In that profile, coverage thresholds and enabled World checks can add required findings; L2/L3 warnings follow `validate.failOnWarning`, while L1 warnings still block. Neither profile adds L4, runs tests on behalf of `--passed`, or bypasses Git hooks. The selected profile is printed. Review configuration and run the required checks before selecting the configured profile. <!-- @work-item-id WI-220 -->
+
 ---
 
 ## CI/CD
@@ -557,3 +573,7 @@ phasegate validate --layer L3
 ```
 
 Use `--json` to inspect `missingTests`, `orphanTests`, preserved references, and intent coverage.
+## Consumer skill selection
+
+<!-- @work-item-id WI-223 -->
+`init --skills consumer` and `install --skills consumer --dry-run` select 27 bundled skills, excluding Phasegate's own release-publisher and skill-creator. Apply install explicitly with `--apply`. The existing core/all sets and default all remain supported. Reconcile preserves the recorded set independently for shared/personal skill roots. No automatic deletion or migration of existing skills occurs when selecting a smaller set.

package/docs/guide/configuration.md

@@ -1,5 +1,29 @@
 # Configuration
 
+## Work-item dependency declarations
+
+<!-- @work-item-id WI-220 -->
+
+A WI description may declare direct dependencies in its frontmatter:
+
+```yaml
+depends_on: [WI-123, WI-124]
+```
+
+A block list of WI IDs is also supported. An explicit `depends_on: []` means no declared dependencies; an omitted field means unknown, not an empty dependency set. Do not add empty declarations to old WIs without reviewing their dependencies. This is separate from phase configuration's `dependsOn` and is not evidence of semantic design approval.
+
+The dependency-specific reader diagnoses malformed lists, duplicate keys and invalid WI IDs. The existing metadata reader retains its previous behavior; adding this declaration does not itself enable a new blocking gate.
+
+For implementation writes permitted by a valid Full Mode session, the candidate runtime checks the session WI and its declared transitive dependencies and prints advisory reflection warnings to stderr. Existing session permission and exit 0 are retained, including when dependency information is incomplete or unreadable. Inception/product edits remain outside this additional check; `storyReflection.enabled: false` disables it. An omitted dependency declaration is reported as unverified, not silently interpreted as no dependencies.
+
+The session advisory uses `paths.inceptionDocs` and `paths.designDocs` consistently for dependency discovery, design artifacts, reflection mappings, and legacy aliases. Existing mapping templates retain their canonical `docs/inception/` and `docs/product/construction/` prefixes; this session path resolves those prefixes to the configured roots. Product mappings outside construction, such as `docs/product/units/`, are unchanged. Invalid roots are reported as unverified rather than falling back to default directories. Older non-session reflection calls retain their previous behavior.
+
+This checks configured reflection annotations, not semantic approval. A `fix` item needs reflection in at least one configured product candidate per affected unit; choosing the semantically relevant categories remains a review responsibility. Missing required design artifacts are reported as unverified in advisory mode.
+
+For the authenticated Full Mode session path, v3 configuration may explicitly select `agentIntegration.preToolUse.dependencyReflection: "enforce"` (or `"advisory"`, the default behavior when omitted). No setting is added automatically. Enforce mode blocks known missing reflection and required artifacts; `storyReflection.enabled: false` still disables this check. Incomplete dependency information falls back to the existing Unit-wide reflection check and reports an unverified warning, even if that fallback passes. Read/configuration failures retain the existing session permission with an unverified warning. This is not a fail-closed semantic approval system.
+
+Repair the indicated inception and product documents separately, obtain any required upstream decisions, and retry the implementation operation. WI inception Markdown design repair is no longer subjected to downstream implementation gates; protected-file checks, source-root overlaps, existing shared-plan/description gates, product gates, and implementation paths remain enforced. Do not treat adding a tag alone as design approval. Standard-gate CLI tests cover both unreflected existing product documents and missing product documents followed by repair and resumption.
+
 ## phasegate.config.json
 
 Place at project root. Generated by `npx phasegate init`.
@@ -666,9 +690,11 @@ Introduced in ISSUE-007 Wave 1 (v0.65.0) and wired into the pre-tool-use hook by
 
 Generate or refresh the snapshot with `npx phasegate baseline` (`--dry-run` to inspect, `--force` to overwrite, `--paths <glob,glob,...>` to scope, `--json` for CI-friendly output). See the [Baseline section in CLI Reference](cli-reference.md#baseline-retrofit-grandfather) for details.
 
-#### `agentIntegration` (Stop hook strict mode)
+#### `agentIntegration` (Hook controls)
+
+Controls agent-side hook behavior. In v3 configuration, optional `preToolUse.enabled` and `postToolUse.enabled` boolean values override the legacy `harnesses.agentLessonCollection` and `harnesses.cascadeUpdate` mappings respectively. When omitted, each legacy value is preserved (default `true` when that legacy key is also absent). No existing config is rewritten automatically. These controls do not remove protected-file or trust-root enforcement. <!-- @work-item-id WI-220 -->
 
-Controls how phasegate's agent-side hooks integrate with Claude Code. Currently only `stopHook.enforce` is exposed.
+The independent keys require a version whose v3 schema supports them. Do not add them while older schema readers are still in use. Before downgrading, restore the configuration saved before adding these keys. There is currently no `config:plan` intent for these fields: use a human-reviewed, out-of-agent-hook edit under the trust-root policy rather than asking the agent to rewrite its own protection configuration.
 
 ```jsonc
 {

package/docs/guide/hooks-integration.md

@@ -82,7 +82,7 @@ This separation is intentional:
 - **Post = "is what was written valid?"** — concerns the resulting code's quality.
 - **Stop = "is the session ready to end?"** — concerns the cumulative state across the session.
 
-If you expect L1 lint (e.g., missing `@unit` annotation) to **block** a Write before it happens, that is by design **not** the case. The PreToolUse hook intentionally does not run lint, because lint requires the resulting file content (which only exists after the write). Lint violations surface as **PostToolUse** decision JSON (`decision: "block"`) and trigger Claude Code to retry.
+The PreToolUse hook does not run lint, because lint requires the resulting file content. The packaged `phasegate hook post-tool-use` command reports lint failures as advisory stderr with exit 0; it does not emit a block decision or request automatic retries. Separate shell hooks such as `analyze-errors-hook.sh` have their own output contract and are not changed by this packaged-command behavior. Commit and CI checks remain independent enforcement points.
 
 ### PreToolUse (before file write)
 - Enforces Phase Gate: blocks writing to source files if required design documents don't exist
@@ -114,6 +114,12 @@ Use /quick-implementor skill for version changes in package.json.
 - Runs Biome AST rules automatically
 - Provides immediate feedback on violations
 
+<!-- @work-item-id WI-220 -->
+
+The packaged command resolves direct-edit and complete patch targets relative to the payload's working directory, then runs lint from the project's configuration root. Multiple targets are retained. Analysis keeps the full dependency graph; only the reported diagnostics are scoped. Unknown shell commands and incomplete targets retain full lint rather than a potentially incomplete target list.
+
+Read/Glob/Grep and disabled hooks finish silently without starting lint. The lint subprocess has a five-second limit; timeout is reported as **validation incomplete**, not a pass. It does not automatically retry. Run `phasegate lint` explicitly when ready to complete validation. This timeout covers the child lint process, not the host runtime's own hook timeout.
+
 ### Stop (before session end)
 - Runs `phasegate:complete-check` (L2-L4 full validation)
 - The built-in Stop hook runs the packaged PhaseGate CLI command; downstream projects do not need to provide `scripts/harness/cli/complete-check.ts`.

package/docs/guide/skills-overview.md

@@ -1,5 +1,8 @@
 # Skills Overview
 
+<!-- @work-item-id WI-223 -->
+For consumer projects, explicitly select `phasegate install --skills consumer --dry-run` (then `--apply` after review). This deploys 27 skills, excluding the Phasegate-maintainer-only `release-publisher` and `skill-creator`. Legacy `core` (7), `all` (29), and the omitted-option default (`all`) remain unchanged. `init` also accepts `consumer`. Reconcile preserves the set recorded in each skill root's `.harness-version`; missing/invalid/unknown metadata retains the legacy `all` fallback. Changing sets does not delete previously installed or user-owned skills. This is audience separation, not a claim of language-independent test tooling.
+
 Phasegate provides 29 skills covering the full AIDLC (AI-Driven Development Life Cycle). `npx phasegate init` and project `npx phasegate install` deploy skill bodies to root `skills/` and expose them to enabled agents through `.claude/skills/`, `.codex/skills/`, or `.agents/skills/` links. Personal install instead writes real local-only per-agent skill directories. <!-- @work-item-id WI-210 --> <!-- @work-item-id WI-385 -->
 
 Bundled `SKILL.md` files include `languages: [typescript]` frontmatter so PhaseGate can distinguish current TypeScript-oriented guidance from future language-specific skill variants. The metadata is advisory for applicability and does not prevent non-TypeScript projects from installing the catalog. <!-- @work-item-id WI-212 -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.340.0",
+  "version": "0.341.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",
@@ -47,6 +47,7 @@
     "phasegate": "bin/phasegate"
   },
   "scripts": {
+    "pack:runtime": "node scripts/pack-runtime.mjs",
     "phasegate": "npx tsx scripts/harness/main.ts",
     "phasegate:status": "npx tsx scripts/harness/main.ts phasegate:status",
     "phasegate:enable": "npx tsx scripts/harness/main.ts enable-feature",

package/scripts/harness/agent-integration/application/usecases/handle-post-tool-use-usecase.ts

@@ -1,6 +1,7 @@
 /**
  * @layer application
  * @unit agent-integration
+ * @work-item-id WI-220
  * @story H11-03
  *
  * HandlePostToolUseUseCase
@@ -39,6 +40,9 @@ export class HandlePostToolUseUseCase {
   }
 
   async execute(input: HandlePostToolUseInput): Promise<HandlePostToolUseOutput> {
+    if (input.affectedFilePaths.length === 0 && ['Read', 'Glob', 'Grep'].includes(input.toolName)) {
+      return { executed: false, skipReason: 'READ_ONLY' };
+    }
     const hookEvent = HookEvent.createPostToolUse(input.toolName, input.affectedFilePaths);
     const translationResult = await this.translator.translate(hookEvent);
 

package/scripts/harness/agent-integration/application/usecases/handle-pre-tool-use-usecase.ts

@@ -27,6 +27,7 @@ import type {
 } from "../../domain/ports/full-mode-session-query-port.js";
 import type { PhaseGateQueryPort } from "../../domain/ports/phase-gate-query-port.js";
 import type { StoryReflectionQueryPort } from "../../domain/ports/story-reflection-query-port.js";
+import { StoryReflectionQueryResult } from "../../domain/value-objects/story-reflection-query-result.js";
 import { AsyncHookToCliTranslator } from "../../domain/services/hook-to-cli-translator.js";
 import { HookEvent } from "../../domain/value-objects/hook-event.js";
 import type { BlockMetadata } from "../../domain/value-objects/hook-translation-result.js";
@@ -169,8 +170,15 @@ export class HandlePreToolUseUseCase {
             fullModeResult.dominantCategory,
           );
           if (sessionResult.allowed) {
+            const reflection = await this.checkSessionReflection(input, sessionResult);
+            if (reflection.sessionEnforced && !reflection.passed && !reflection.skipped) {
+              const blocked = HandlePreToolUseUseCase.buildStoryReflectionBlockOutput(input.targetFilePaths[0], reflection.blockers, reflection.warnings);
+              return { ...blocked, error: { message: `[L2-STORY-REFLECTION] 明示設定による依存反映チェック\n${reflection.blockers.join('\n')}\n修正方法: inception/productを単独で編集し、必要な上位判断と設計内容を反映してから同じ操作を再評価してください。タグだけでは意味的承認を証明しません。\n依存不明の場合はdescription.mdのID・所属・depends_onを確認してください。` } };
+            }
+            const warnings = [...reflection.blockers, ...reflection.warnings];
             return {
               shouldBlock: false,
+              ...(warnings.length > 0 ? { storyReflectionWarnings: warnings } : {}),
               fullModeSessionAllowed: {
                 workItemId: sessionResult.workItemId,
                 unit: sessionResult.unit,
@@ -187,7 +195,7 @@ export class HandlePreToolUseUseCase {
               input.targetFilePaths[0],
               fullModeResult,
               guidance,
-              unitIdForGuidance,
+              this.deriveRecoveryUnitId(input.targetFilePaths),
               sessionResult,
             );
           }
@@ -225,6 +233,19 @@ export class HandlePreToolUseUseCase {
     );
   }
 
+  private async checkSessionReflection(
+    input: HandlePreToolUseInput,
+    session: FullModeSessionQueryResult,
+  ): Promise<StoryReflectionQueryResult> {
+    if (!session.active || !session.unit || !session.workItemId ||
+      !this.storyReflectionQueryPort?.checkSessionReflection || !this.resolveStoryReflectionScope(input)) return StoryReflectionQueryResult.skipped();
+    try {
+      return await this.storyReflectionQueryPort.checkSessionReflection(session.unit, session.workItemId);
+    } catch (error) {
+      return StoryReflectionQueryResult.skipped([`WI依存反映は未検証です（既存sessionの許可を維持）: ${error instanceof Error ? error.message : String(error)}`]);
+    }
+  }
+
   private async checkGrandfather(targetFilePaths: readonly string[]): Promise<BaselineGrandfatherCheckResult> {
     if (this.baselineGrandfatherQueryPort === undefined) {
       return {
@@ -352,6 +373,7 @@ export class HandlePreToolUseUseCase {
     HandlePreToolUseUseCase.appendJudgmentContextLines(lines, sessionResult);
     const suggestedSkill = guidance?.suggestedSkill ?? "/story-implementor";
     lines.push(`次のアクション: ${suggestedSkill} スキルを使用して設計フェーズから開始してください。`);
+    lines.push('  inceptionの計画編集と実装を分け、実装は対象Unitごとに設計反映とsession開始を行ってください。');
     if (unitId !== undefined && unitId !== "") {
       if (HandlePreToolUseUseCase.isSessionActiveButRejected(sessionResult)) {
         lines.push(
@@ -362,6 +384,8 @@ export class HandlePreToolUseUseCase {
         `  実装フェーズ開始時: phasegate session begin --mode full --unit ${unitId} --work-item <WI-XXX> --reason "<reason>" --duration 1h`,
       );
       lines.push("  実装完了時: phasegate session end --work-item <WI-XXX>");
+    } else {
+      lines.push('  対象Unitが一意に決まりません。実装対象パスのUnitを確認してください（_crossはsessionのUnitに指定できません）。');
     }
     HandlePreToolUseUseCase.appendGuidanceLines(lines, guidance, unitId);
 
@@ -458,6 +482,17 @@ export class HandlePreToolUseUseCase {
     return `${templatePath}（未配置なら: npx phasegate skills info ${skillMatch[1]}）`;
   }
 
+  private deriveRecoveryUnitId(targetFilePaths: readonly string[]): string | undefined {
+    const projectPaths = this.configQueryPort.getProjectPaths();
+    const units = new Set<string>();
+    for (const targetFilePath of targetFilePaths) {
+      if (HandlePreToolUseUseCase.isUnderInception(targetFilePath, projectPaths.getDocsInception())) continue;
+      const unit = WriteTargetScope.fromPath(targetFilePath, projectPaths)?.unitId;
+      if (unit !== undefined && /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(unit)) units.add(unit);
+    }
+    return units.size === 1 ? [...units][0] : undefined;
+  }
+
   private deriveUnitIdFromPaths(targetFilePaths: readonly string[]): string | undefined {
     const projectPaths = this.configQueryPort.getProjectPaths();
     for (const targetFilePath of targetFilePaths) {

package/scripts/harness/agent-integration/application/usecases/handle-stop-usecase.ts

@@ -2,14 +2,12 @@
  * @layer application
  * @unit agent-integration
  * @story H11-04
+ * @work-item-id WI-220
  *
  * HandleStopUseCase
  * Stop Hook処理のオーケストレーション。ReentryGuardライフサイクル管理の唯一の制御点
  */
 
-import { HookEvent } from '../../domain/value-objects/hook-event.js';
-import { ReentryGuard } from '../../domain/entities/reentry-guard.js';
-import { AsyncHookToCliTranslator } from '../../domain/services/hook-to-cli-translator.js';
 import type { ReentryGuardStatePort } from '../../domain/ports/reentry-guard-state-port.js';
 import type { ConfigQueryPort } from '../../domain/ports/config-query-port.js';
 import type { CliExecutorPort } from '../ports/cli-executor-port.js';
@@ -19,7 +17,8 @@ export interface HandleStopUseCasePorts {
   reentryGuardStatePort: ReentryGuardStatePort;
   cliExecutorPort: CliExecutorPort;
   configQueryPort: ConfigQueryPort;
-  cliCommandRegistryPort: {
+  /** Legacy constructor input; Stop dispatches complete-check directly. */
+  cliCommandRegistryPort?: {
     hasCommand(commandName: string): Promise<boolean>;
     listCommands(): Promise<readonly string[]>;
   };
@@ -37,16 +36,11 @@ export class HandleStopUseCase {
   private readonly reentryGuardStatePort: ReentryGuardStatePort;
   private readonly cliExecutorPort: CliExecutorPort;
   private readonly configQueryPort: ConfigQueryPort;
-  private readonly cliCommandRegistryPort: {
-    hasCommand(commandName: string): Promise<boolean>;
-    listCommands(): Promise<readonly string[]>;
-  };
 
   constructor(ports: HandleStopUseCasePorts) {
     this.reentryGuardStatePort = ports.reentryGuardStatePort;
     this.cliExecutorPort = ports.cliExecutorPort;
     this.configQueryPort = ports.configQueryPort;
-    this.cliCommandRegistryPort = ports.cliCommandRegistryPort;
   }
 
   async execute(input: HandleStopInput): Promise<HandleStopOutput> {

package/scripts/harness/agent-integration/domain/ports/story-reflection-query-port.ts

@@ -5,4 +5,6 @@ import type { StoryReflectionQueryResult } from '../value-objects/story-reflecti
 
 export interface StoryReflectionQueryPort {
   checkReflection(unitId: string): Promise<StoryReflectionQueryResult>;
+  /** WI-220: optional session path, advisory by default; caller supplies authenticated identity. */
+  checkSessionReflection?(unitId: string, workItemId: string): Promise<StoryReflectionQueryResult>;
 }

package/scripts/harness/agent-integration/domain/services/hook-to-cli-translator.ts

@@ -140,7 +140,7 @@ export class HookToCliTranslator {
       throw new CommandNotRegisteredError(commandName);
     }
 
-    return HookTranslationResult.execute(commandName, ['--fast'], 0, 500);
+    return HookTranslationResult.execute(commandName, [...new Set(event.affectedFilePaths)].flatMap((target) => ['--target', target]), 0, 5000);
   }
 
   private translateStop(_event: StopEvent): HookTranslationResult {
@@ -248,7 +248,10 @@ export class AsyncHookToCliTranslator {
     const projectPaths = await (this.configQueryPort as ConfigQueryPort & {
       getProjectPaths(): unknown;
     }).getProjectPaths();
-    const detectedScope = event.targetFilePaths
+    const gatePaths = event.targetFilePaths.filter(filePath => !WriteTargetScope.isInceptionDocument(
+      filePath, projectPaths as Parameters<typeof WriteTargetScope.fromPath>[1],
+    ));
+    const detectedScope = gatePaths
       .map((filePath) => WriteTargetScope.fromPath(filePath, projectPaths as Parameters<typeof WriteTargetScope.fromPath>[1]))
       .find((scope): scope is WriteTargetScope => scope !== null);
 
@@ -272,7 +275,7 @@ export class AsyncHookToCliTranslator {
 
     const phaseGateResult = await this.phaseGateQueryPort.checkGate(
       detectedScope,
-      event.targetFilePaths[0],
+      gatePaths.find(filePath => WriteTargetScope.fromPath(filePath, projectPaths as Parameters<typeof WriteTargetScope.fromPath>[1]) !== null),
     );
     if (!phaseGateResult.hasPassed()) {
       return HookTranslationResult.block({
@@ -292,7 +295,7 @@ export class AsyncHookToCliTranslator {
     });
   }
 
-  private async translatePostToolUse(_event: PostToolUseEvent): Promise<HookTranslationResult> {
+  private async translatePostToolUse(event: PostToolUseEvent): Promise<HookTranslationResult> {
     const isEnabled = await this.configQueryPort.isHookEnabled('post-tool-use');
     if (!isEnabled) {
       return HookTranslationResult.skip('HOOK_DISABLED');
@@ -304,7 +307,7 @@ export class AsyncHookToCliTranslator {
       throw new CommandNotRegisteredError(commandName);
     }
 
-    return HookTranslationResult.execute(commandName, ['--fast'], 0, 500);
+    return HookTranslationResult.execute(commandName, [...new Set(event.affectedFilePaths)].flatMap((target) => ['--target', target]), 0, 5000);
   }
 
   private async translateStop(_event: StopEvent): Promise<HookTranslationResult> {

package/scripts/harness/agent-integration/domain/value-objects/hook-translation-result.ts

@@ -6,7 +6,7 @@
  * HookEvent → CLI実行指示への変換結果
  */
 
-export type SkipReason = 'REENTRY_DETECTED' | 'HOOK_DISABLED' | 'TIMEOUT_EXCEEDED';
+export type SkipReason = 'REENTRY_DETECTED' | 'HOOK_DISABLED' | 'TIMEOUT_EXCEEDED' | 'READ_ONLY';
 
 export type BlockReason = 'PROTECTED_FILE' | 'PHASE_GATE' | 'FULL_MODE_REQUIRED';
 

package/scripts/harness/agent-integration/domain/value-objects/story-reflection-query-result.ts

@@ -14,6 +14,7 @@ export class StoryReflectionQueryResult {
   readonly blockers: readonly string[];
   readonly warnings: readonly string[];
   readonly skipped: boolean;
+  declare readonly sessionEnforced?: true;
 
   private constructor(
     passed: boolean,
@@ -27,8 +28,8 @@ export class StoryReflectionQueryResult {
     this.skipped = skipped;
   }
 
-  static pass(): StoryReflectionQueryResult {
-    return new StoryReflectionQueryResult(true, [], [], false);
+  static pass(warnings: string[] = []): StoryReflectionQueryResult {
+    return new StoryReflectionQueryResult(true, [], warnings, false);
   }
 
   static skipped(warnings: string[] = []): StoryReflectionQueryResult {
@@ -45,6 +46,13 @@ export class StoryReflectionQueryResult {
     return new StoryReflectionQueryResult(false, blockers, warnings, false);
   }
 
+  /** Only trusted configuration readers may mark the optional session enforcement path. */
+  withSessionEnforcement(): StoryReflectionQueryResult {
+    return Object.assign(new StoryReflectionQueryResult(this.passed, this.blockers, this.warnings, this.skipped), {
+      sessionEnforced: true as const,
+    });
+  }
+
   hasPassed(): boolean {
     return this.passed;
   }

package/scripts/harness/agent-integration/domain/value-objects/write-target-scope.ts

@@ -61,6 +61,9 @@ export class WriteTargetScope {
       if (sourceMatch !== null) {
         const [unitId] = sourceMatch;
         if (unitId !== undefined) {
+          // A source-root file (e.g. main.ts) is not a Unit directory.
+          // Keep nested paths, including dotted directory names, under the gate.
+          if (sourceMatch.length === 1 && unitId.includes('.')) continue;
           return WriteTargetScope.create({ level: 3, unitId });
         }
       }
@@ -124,6 +127,15 @@ export class WriteTargetScope {
     return null;
   }
 
+  /** Phase-1 Markdown repair is not implementation; source-root overlaps remain gated. */
+  static isInceptionDocument(filePath: string, projectPaths: ProjectPaths): boolean {
+    const normalized = normalize(filePath);
+    return normalized.toLowerCase().endsWith('.md')
+      && matchPrefix(normalized, projectPaths.getDocsInception()) !== null
+      && !projectPaths.getSource().some(root => matchPrefix(normalized, root) !== null)
+      && WriteTargetScope.fromPath(normalized, projectPaths)?.level === 3;
+  }
+
   equals(other: WriteTargetScope): boolean {
     return this.level === other.level && this.unitId === other.unitId && this.storyId === other.storyId;
   }

package/scripts/harness/agent-integration/infrastructure/adapters/child-process-cli-executor-adapter.ts

@@ -7,38 +7,47 @@
  * CliExecutorPort の実装。子プロセスで CLI コマンドを実行する
  */
 
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
+import { statSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { CliExecutorPort, CliExecutionResult } from '../../application/ports/cli-executor-port.js';
 import { TimeoutError } from '../../application/ports/cli-executor-port.js';
 
+const tsxCliPath = createRequire(import.meta.url).resolve('tsx/cli');
+
 function getHarnessMainPath(): string {
   return resolve(dirname(fileURLToPath(import.meta.url)), '../../../main.ts');
 }
 
 /**
  * CommandName を実行可能なコマンドに変換する
- * 例: 'phasegate:lint' → ['npx', 'tsx', '<package>/scripts/harness/main.ts', 'phasegate:lint']
+ * 例: 'phasegate:lint' → [node, '<package>/tsx/cli', '<package>/scripts/harness/main.ts', 'phasegate:lint']
  * テスト時は直接スクリプトパスで execute を呼ぶことも可能
  */
 function resolveCommand(commandName: string): { cmd: string; args: string[] } {
   if (commandName.startsWith('phasegate:')) {
+    const compiledMain = resolve(dirname(getHarnessMainPath()), 'main.js');
+    let compiled = false;
+    try { compiled = statSync(compiledMain).isFile(); } catch { /* Source-only packages retain the TS entry. */ }
     return {
-      cmd: 'npx',
-      args: ['tsx', getHarnessMainPath(), commandName],
+      cmd: process.execPath,
+      args: compiled ? [compiledMain, commandName] : [tsxCliPath, getHarnessMainPath(), commandName],
     };
   }
 
   // Legacy extension commands may still be provided as project-local wrappers.
   const slug = commandName.replace('phasegate:', '');
   return {
-    cmd: 'npx',
-    args: ['tsx', `scripts/harness/cli/${slug}.ts`],
+    cmd: process.execPath,
+    args: [tsxCliPath, `scripts/harness/cli/${slug}.ts`],
   };
 }
 
 export class ChildProcessCliExecutorAdapter implements CliExecutorPort {
+  constructor(private readonly options: { cwd?: string } = {}) {}
+
   async execute(
     command: string,
     args: string[],
@@ -49,9 +58,9 @@ export class ChildProcessCliExecutorAdapter implements CliExecutorPort {
       let spawnArgs: string[];
 
       // If the command looks like a file path (contains / or .ts), run it directly
-      if (command.includes('/') || command.endsWith('.ts')) {
-        cmd = 'npx';
-        spawnArgs = ['tsx', command, ...args];
+      if (command.includes('/') || command.includes('\\') || command.endsWith('.ts')) {
+        cmd = process.execPath;
+        spawnArgs = [tsxCliPath, command, ...args];
       } else {
         const resolved = resolveCommand(command);
         cmd = resolved.cmd;
@@ -61,11 +70,16 @@ export class ChildProcessCliExecutorAdapter implements CliExecutorPort {
       let stdout = '';
       let stderr = '';
       let timedOut = false;
+      let closed = false;
+      let cleanupDone = false;
 
       const child = spawn(cmd, spawnArgs, {
         stdio: ['pipe', 'pipe', 'pipe'],
         shell: false,
+        cwd: this.options.cwd,
+        detached: process.platform !== 'win32',
       });
+      child.stdin?.end();
 
       child.stdout?.on('data', (data: Buffer) => {
         stdout += data.toString();
@@ -76,21 +90,57 @@ export class ChildProcessCliExecutorAdapter implements CliExecutorPort {
       });
 
       let timer: NodeJS.Timeout | undefined;
+      let killTimer: NodeJS.Timeout | undefined;
+      const finishTimeout = () => {
+        if (closed && cleanupDone) reject(new TimeoutError(command, timeoutMs!));
+      };
+      const signalTree = (signal: NodeJS.Signals) => {
+        if (child.pid === undefined) return;
+        try {
+          process.kill(-child.pid, signal);
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error;
+        }
+      };
 
       if (timeoutMs !== undefined) {
         timer = setTimeout(() => {
           timedOut = true;
-          child.kill('SIGTERM');
-          reject(new TimeoutError(command, timeoutMs));
+          try {
+            if (process.platform === 'win32' && child.pid !== undefined) {
+              const cleanup = spawnSync('taskkill', ['/PID', String(child.pid), '/T', '/F'], { shell: false, timeout: 5000 });
+              if (cleanup.error || cleanup.status !== 0) throw cleanup.error ?? new Error(`Process tree cleanup failed: ${cleanup.status}`);
+              cleanupDone = true;
+              finishTimeout();
+            } else {
+              signalTree('SIGTERM');
+              // Keep the group cleanup even if its leader closes before descendants.
+              killTimer = setTimeout(() => {
+                try {
+                  signalTree('SIGKILL');
+                  cleanupDone = true;
+                  finishTimeout();
+                } catch (error) {
+                  reject(error);
+                }
+              }, 250);
+            }
+          } catch (error) {
+            reject(error);
+          }
         }, timeoutMs);
       }
 
       child.on('close', (exitCode) => {
+        closed = true;
         if (timer) clearTimeout(timer);
-        if (timedOut) return;
+        if (timedOut) {
+          finishTimeout();
+          return;
+        }
 
         resolve({
-          exitCode: exitCode ?? 0,
+          exitCode: exitCode ?? 1,
           stdout,
           stderr,
           timedOut: false,
@@ -99,6 +149,7 @@ export class ChildProcessCliExecutorAdapter implements CliExecutorPort {
 
       child.on('error', (error) => {
         if (timer) clearTimeout(timer);
+        if (killTimer) clearTimeout(killTimer);
         reject(error);
       });
     });