phasegate 0.283.0 → 0.335.0

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

@@ -5,6 +5,7 @@
  * @work-item-id WI-109
  * @work-item-id WI-189
  * @work-item-id WI-305
+ * @work-item-id WI-332
  *
  * Pre-commit CLI entry.
  * Runs L2 validators against staged TypeScript files AND design-document
@@ -27,6 +28,7 @@ import type { ValidateMetadataCommandOutput } from "../traceability-model/presen
 import type { AggregatedValidationReport } from "../validator-system/application/dto/aggregated-validation-report.js";
 import type { ValidationResultContract } from "../validator-system/application/dto/validation-result-contract.js";
 import { createValidatorSystemModule } from "../validator-system/composition-root.js";
+import { isEffectivelyPassed } from "../validator-system/domain/services/effective-severity-policy.js";
 import { HumanValidationResultFormatter } from "../validator-system/presentation/formatters/human-validation-result-formatter.js";
 import { createWorldModelModule } from "../world-model/index.js";
 
@@ -293,9 +295,19 @@ function getStagedDesignChangeFiles(): string[] {
   }
 }
 
+/**
+ * WI-332 / ADR-017: pre-commit 経路には config の failOnWarning 配線が存在しないため、
+ * ADR-017 の既定値 (false) に固定する。validate.failOnWarning を pre-commit にも効かせる
+ * 判断をする場合は、この定数を options 経由の配線に置き換えること。
+ */
+const PRE_COMMIT_FAIL_ON_WARNING = false;
+
 function buildReport(results: readonly ValidationResultContract[]): AggregatedValidationReport {
-  const passed = results.filter((r) => r.passed && !r.skipped).length;
-  const failed = results.filter((r) => !r.passed && !r.skipped).length;
+  // WI-332 / ADR-017: 手動集約 (`failed === 0` の raw passed 判定) をやめ、
+  // validate / ci-check / complete-check と同じ共有実効判定 isEffectivelyPassed を通す。
+  // warning-only の validator failure は既定で effectively passed = exit 0。
+  const passed = results.filter((r) => !r.skipped && isEffectivelyPassed(r, PRE_COMMIT_FAIL_ON_WARNING)).length;
+  const failed = results.filter((r) => !r.skipped && !isEffectivelyPassed(r, PRE_COMMIT_FAIL_ON_WARNING)).length;
   const skipped = results.filter((r) => r.skipped).length;
   const allErrors = results.flatMap((r) => r.errors);
   const errorCount = allErrors.filter((e) => e.severity === "error").length;
@@ -452,7 +464,9 @@ export async function validateBypassTrailers(
 }
 
 function classifyValidatorFailure(result: ValidationResultContract): BypassBlockerClass | undefined {
-  if (result.passed || result.skipped) return undefined;
+  // WI-332: blocker 分類も buildReport と同じ実効判定を通す。warning-only failure は
+  // exit 0 (effectively passed) なので、bypass audit の blocker としても数えない。
+  if (isEffectivelyPassed(result, PRE_COMMIT_FAIL_ON_WARNING)) return undefined;
   const nonBypassable = NON_BYPASSABLE_VALIDATOR_IDS.includes(result.validatorId);
   return {
     code: result.validatorId,

package/scripts/harness/main.ts

@@ -41,11 +41,11 @@ import {
   rm as fsRm,
   writeFile as fsWriteFile,
 } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+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";
@@ -75,7 +75,7 @@ import {
 import { FileSystemStoryReflectionAdapter } from "./phase-dependency-model/infrastructure/filesystem/file-system-story-reflection-adapter.js";
 import { StoryReflectionStatusPresenter } from "./phase-dependency-model/presentation/cli/story-reflection-status-presenter.js";
 import { buildPhase2Extensions } from "./phase2-extensions/composition-root.js";
-import { createQuickModeCompositionRoot } from "./quick-mode/composition-root.js";
+import { createQuickModeCompositionRoot, type QuickModeCompositionRootOptions } from "./quick-mode/composition-root.js";
 import { buildRegressionSuite } from "./regression-suite/composition-root.js";
 import type { SkillSet } from "./setup/skill-deployer.js";
 import {
@@ -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;
@@ -228,7 +241,7 @@ Commands:
 
   lint                         Run lint checks (--json, --target <path>)
 
-  validate                     Run validators (--layer L2|L3|L4|all; L0 prints runtime hook info, --unit, --format human|agent|ci|json, --json)
+  validate                     Run validators (--layer L0|L2|L3|L4|all; L0 prints runtime hook info, --unit, --format human|agent|ci|json, --json)
   ci-check                     CI check (--quick for quick mode, --fail-on-reject, --dry-run, --files)
   check-change-category        Classify changed paths for quick mode (--paths <csv>, --format human|json)
 
@@ -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
@@ -501,6 +519,15 @@ function parseValidateFormat(args: readonly string[]): "human" | "agent" | "ci"
   throw new Error(`Invalid --format value for validate: '${raw}'. Supported values: human, agent, ci, json.`);
 }
 
+function parseValidateLayer(args: readonly string[]): "L0" | "L2" | "L3" | "L4" | "all" | undefined {
+  const raw = parseFlag(args, "--layer");
+  if (raw === undefined) return undefined;
+  if (raw === "L0" || raw === "L2" || raw === "L3" || raw === "L4" || raw === "all") return raw;
+
+  const lintGuidance = raw === "L1" ? "\nL1 は `npx phasegate lint` で実行してください。" : "";
+  throw new Error(`不正な --layer 値: ${raw}\n有効値: L0, L2, L3, L4, all${lintGuidance}`);
+}
+
 function levenshtein(a: string, b: string): number {
   const m = a.length;
   const n = b.length;
@@ -553,12 +580,25 @@ function validateKnownFlags(args: readonly string[], known: readonly string[]):
   return null;
 }
 
+/**
+ * Full Mode session が許可する変更カテゴリ。
+ *
+ * WI-348: 照合相手は quick-mode の `ChangeCategoryValue`
+ * (`bugfix | docs | test | config | feature | domain | api`) であり、
+ * レイヤー名（application / infrastructure / presentation）ではない。
+ * 旧実装はレイヤー名語彙を書き出していたため、交差が domain / config のみとなり
+ * session を張っても feature / api の書き込みがブロックされ続けていた。
+ * ChangeCategory の全語彙を許可し、session のスコープ制御は
+ * unit / 期限 / target path 側の判定に委ねる。
+ */
 const FULL_MODE_SESSION_ALLOWED_CATEGORIES = Object.freeze([
-  "domain",
-  "application",
-  "infrastructure",
-  "presentation",
+  "bugfix",
+  "docs",
+  "test",
   "config",
+  "feature",
+  "domain",
+  "api",
 ]);
 
 interface FullModeSessionFile {
@@ -878,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.
@@ -1901,6 +1968,32 @@ async function loadResolvedConfig(command?: string): Promise<HarnessConfigV2 | u
   }
 }
 
+/**
+ * WI-351: quick-mode composition root へ解決済み configPath / rootDir を注入する。
+ *
+ * 無指定だと `HarnessConfigQuickModeConfigAdapter` は `process.cwd()/phasegate.config.json`、
+ * `FsFileExistenceAdapter` は `process.cwd()` を基準にする。サブディレクトリから CLI を
+ * 実行すると config を見失い、相対パスの存在判定（= CREATE/MODIFY 推定）も
+ * プロジェクトルート基準の hook とずれて分類結果が食い違う。
+ * config-foundation が上方探索で解決した sourcePath を基準に揃える
+ * （hook 側で WI-346 が行ったのと同じ整合）。
+ * config 未検出・不正時は従来どおり cwd 基準へフォールバックする（fail-open）。
+ */
+async function resolveQuickModeCompositionOptions(): Promise<QuickModeCompositionRootOptions> {
+  try {
+    const configModule = createConfigFoundationModule();
+    const { sourcePath } = await configModule.usecases.loadResolvedConfigUseCase.execute();
+    if (typeof sourcePath === "string" && sourcePath !== "") {
+      const configDir = dirname(sourcePath);
+      const rootDir = basename(configDir) === ".phasegate-local" ? dirname(configDir) : configDir;
+      return { configPath: sourcePath, rootDir };
+    }
+  } catch {
+    // 解決できない場合はフォールバック（下の return）
+  }
+  return { rootDir: getProjectRoot() };
+}
+
 async function loadWorldResolvedConfig() {
   try {
     const configModule = createConfigFoundationModule();
@@ -2888,7 +2981,7 @@ async function main(): Promise<void> {
       // ── validator-system ──
       case "validate": {
         const mod = createValidatorSystemModule(toValidatorSystemConfig(resolvedConfig));
-        const layer = parseFlag(args, "--layer") as "L0" | "L2" | "L3" | "L4" | "all" | undefined;
+        const layer = parseValidateLayer(args);
         const unit = parseFlag(args, "--unit");
         const phase = parseFlag(args, "--phase");
         const format = parseValidateFormat(args) ?? (json ? "ci" : undefined);
@@ -2917,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");
@@ -2956,7 +3052,7 @@ async function main(): Promise<void> {
           );
           return;
         }
-        const mod = createQuickModeCompositionRoot();
+        const mod = createQuickModeCompositionRoot(await resolveQuickModeCompositionOptions());
         const paths = parseFlag(args, "--paths");
         const format = parseFlag(args, "--format") as "human" | "json" | undefined;
         const failOnFullRequired = hasFlag(args, "--fail-on-full-required");
@@ -3193,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");
@@ -3205,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";
@@ -3216,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";
@@ -3227,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";
@@ -3238,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";
@@ -3249,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";
@@ -3260,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");
@@ -3283,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");
@@ -3303,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 });
@@ -3314,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,22 +1,36 @@
 /**
  * @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 type { PhaseNode } from '../../domain/values/phase-node.js';
-import type { PlanningMode } from '../../domain/values/planning-mode.js';
-import { PlanEvidence } from '../../domain/values/plan-evidence.js';
+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";
 
 export interface MarkdownPlanDocumentReaderDeps {
   readonly rootDir: string;
 }
 
-const QA_SECTION_PATTERN = /^## QA\b/m;
-const QUESTION_PATTERN = /^Q:/gm;
-const ANSWER_PATTERN = /^A:/gm;
+/**
+ * WI-358 (issue #29): 見出しの表記ゆれで Planning Mode の evidence 判定が落ちる罠を潰す。
+ *
+ * 旧パターンは "QA" 綴りしか受け付けず、エージェントが自然に書く `## Q&A` /
+ * 全角の `## Q＆A` を弾いていた。中身は同一なのに phase gate だけが落ち、
+ * 原因が見出しの綴りだと気付けないまま止まる。
+ *
+ * 緩和方向のみの変更であり、既存の `## QA` / `## 4. QA（不明点・確認事項）` は
+ * すべて従来どおりマッチする。
+ */
+const QA_SECTION_PATTERN = /^##+\s*(?:\d+[.．]\s*)?Q[&＆]?A\b/m;
+const QUESTION_PATTERN = /^(?:Q:|###\s*\[Question\])/gm;
+const LEGACY_ANSWER_PATTERN = /^A:/gm;
+const STRUCTURED_ANSWER_PATTERN = /^\[Answer\][ \t]*$/gm;
+const ANSWER_BODY_BOUNDARY_PATTERN = /^(?:###\s*\[Question\]|#{1,6}\s+)/m;
 
 export class MarkdownPlanDocumentReader implements PlanDocumentReaderPort {
   private readonly rootDir: string;
@@ -29,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();
 
@@ -43,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,
@@ -55,7 +70,7 @@ export class MarkdownPlanDocumentReader implements PlanDocumentReaderPort {
 
     let content: string;
     try {
-      content = await readFile(absolutePath, 'utf8');
+      content = await readFile(absolutePath, "utf8");
     } catch {
       return PlanEvidence.create({
         exists: false,
@@ -66,11 +81,7 @@ export class MarkdownPlanDocumentReader implements PlanDocumentReaderPort {
 
     const hasQaSection = QA_SECTION_PATTERN.test(content);
     const qaComplete = this.isQaComplete(content, hasQaSection, expectedMode);
-    const planningModeMatch = this.detectPlanningModeMatch(
-      content,
-      hasQaSection,
-      expectedMode,
-    );
+    const planningModeMatch = this.detectPlanningModeMatch(content, hasQaSection, expectedMode);
 
     return PlanEvidence.create({
       exists: true,
@@ -79,16 +90,12 @@ export class MarkdownPlanDocumentReader implements PlanDocumentReaderPort {
     });
   }
 
-  private isQaComplete(
-    content: string,
-    hasQaSection: boolean,
-    expectedMode: PlanningMode,
-  ): boolean {
+  private isQaComplete(content: string, hasQaSection: boolean, expectedMode: PlanningMode): boolean {
     if (expectedMode.requiresAnsweredQa()) {
       if (!hasQaSection) return false;
       const qaSection = this.extractQaSection(content);
       const questionCount = (qaSection.match(QUESTION_PATTERN) ?? []).length;
-      const answerCount = (qaSection.match(ANSWER_PATTERN) ?? []).length;
+      const answerCount = this.countAnswers(qaSection);
       return questionCount > 0 && questionCount === answerCount;
     }
 
@@ -99,16 +106,12 @@ export class MarkdownPlanDocumentReader implements PlanDocumentReaderPort {
     return true;
   }
 
-  private detectPlanningModeMatch(
-    content: string,
-    hasQaSection: boolean,
-    expectedMode: PlanningMode,
-  ): boolean {
+  private detectPlanningModeMatch(content: string, hasQaSection: boolean, expectedMode: PlanningMode): boolean {
     if (expectedMode.requiresAnsweredQa()) {
       if (!hasQaSection) return false;
       const qaSection = this.extractQaSection(content);
       const questionCount = (qaSection.match(QUESTION_PATTERN) ?? []).length;
-      const answerCount = (qaSection.match(ANSWER_PATTERN) ?? []).length;
+      const answerCount = this.countAnswers(qaSection);
       return questionCount > 0 && answerCount === questionCount;
     }
 
@@ -121,14 +124,42 @@ export class MarkdownPlanDocumentReader implements PlanDocumentReaderPort {
 
   private extractQaSection(content: string): string {
     const match = content.match(QA_SECTION_PATTERN);
-    if (!match || match.index === undefined) return '';
+    if (!match || match.index === undefined) return "";
 
     const start = match.index;
-    const nextSectionMatch = content.slice(start + match[0].length).match(/^## /m);
-    const end = nextSectionMatch?.index
-      ? start + match[0].length + nextSectionMatch.index
-      : content.length;
+    const sectionContentStart = start + match[0].length;
+    const sectionContent = content.slice(sectionContentStart);
+    const headingMarker = match[0].match(/^##+/)?.[0];
+    if (!headingMarker) return "";
+
+    const sameLevelHeadingPattern = new RegExp(`^${headingMarker}(?!#)[ \\t]+(.+)$`, "gm");
+    let end = content.length;
+    for (const headingMatch of sectionContent.matchAll(sameLevelHeadingPattern)) {
+      if (/^\[Question\](?:\s|$)/.test(headingMatch[1].trimStart())) continue;
+      if (headingMatch.index !== undefined) {
+        end = sectionContentStart + headingMatch.index;
+        break;
+      }
+    }
 
     return content.slice(start, end);
   }
+
+  private countAnswers(qaSection: string): number {
+    const legacyAnswerCount = (qaSection.match(LEGACY_ANSWER_PATTERN) ?? []).length;
+    let structuredAnswerCount = 0;
+
+    for (const answerMatch of qaSection.matchAll(STRUCTURED_ANSWER_PATTERN)) {
+      if (answerMatch.index === undefined) continue;
+      const bodyStart = answerMatch.index + answerMatch[0].length;
+      const followingContent = qaSection.slice(bodyStart);
+      const boundaryMatch = followingContent.match(ANSWER_BODY_BOUNDARY_PATTERN);
+      const answerBody =
+        boundaryMatch?.index === undefined ? followingContent : followingContent.slice(0, boundaryMatch.index);
+      const hasBody = answerBody.split(/\r?\n/).some((line) => line.trim().length > 0);
+      if (hasBody) structuredAnswerCount += 1;
+    }
+
+    return legacyAnswerCount + structuredAnswerCount;
+  }
 }

package/scripts/harness/phase2-extensions/presentation/handlers/check-freshness-handler.ts

@@ -2,8 +2,8 @@
  * @layer presentation
  * @unit phase2-extensions
  */
-import type { CheckDocFreshnessUseCase } from '../../application/usecases/check-doc-freshness-usecase.js';
-import { FreshnessResultFormatter } from '../formatters/freshness-result-formatter.js';
+import type { CheckDocFreshnessUseCase } from "../../application/usecases/check-doc-freshness-usecase.js";
+import { FreshnessResultFormatter } from "../formatters/freshness-result-formatter.js";
 
 export class CheckFreshnessHandler {
   private readonly formatter = new FreshnessResultFormatter();
@@ -12,26 +12,34 @@ export class CheckFreshnessHandler {
 
   async handle(args: string[]): Promise<{ exitCode: number; stdout: string }> {
     let targetPattern: string | undefined;
-    let format: 'text' | 'json' = 'text';
+    let format: "text" | "json" = "text";
     let dryRun = false;
 
     for (let index = 0; index < args.length; index += 1) {
       const arg = args[index];
-      if (arg === '--pattern') {
+      if (arg === "--pattern") {
         targetPattern = args[index + 1];
         index += 1;
-      } else if (arg === '--format') {
-        format = (args[index + 1] as 'text' | 'json') ?? 'text';
+      } else if (arg === "--format") {
+        format = (args[index + 1] as "text" | "json") ?? "text";
         index += 1;
-      } else if (arg === '--dry-run') {
+      } else if (arg === "--dry-run") {
         dryRun = true;
       }
     }
 
     const result = await this.useCase.execute({ targetPattern, format, dryRun });
+    // WI-359: `--dry-run` は「副作用なしで診断のみ」（skills/doc-health-checker/SKILL.md）であり、
+    // シナリオ仕様 SC-P2-002 の期待結果も exit 0 である。従来は dryRun をパースだけして
+    // 捨てており、error 閾値超過の文書が 1 件でもあると診断のみの実行でも exit 1 になっていた。
+    // その結果 SC-P2-002 の e2e は「コードを一切変えなくても暦の経過だけで落ちる」状態になっていた。
+    // 実運用の鮮度ゲートは L4-004（`validate --layer L4`）が担い、そちらは本 handler を
+    // 経由しないため、dry-run を report-only にしてもゲートは緩まない。
+    // フラグ未指定時の exit 1 は従来どおり維持する。
+    const exitCode = dryRun ? 0 : result.summary.error > 0 ? 1 : 0;
     return {
-      exitCode: result.summary.error > 0 ? 1 : 0,
-      stdout: format === 'json' ? this.formatter.formatJson(result) : this.formatter.formatText(result),
+      exitCode,
+      stdout: format === "json" ? this.formatter.formatJson(result) : this.formatter.formatText(result),
     };
   }
 }