phasegate 0.134.0 → 0.136.0

package/docs/templates/ci/aidlc-gate.yml

@@ -0,0 +1,97 @@
+# Phasegate — PR検証ワークフロー
+#
+# 使い方:
+#   このファイルを .github/workflows/aidlc-gate.yml にコピーして使用する。
+#
+# 実行タイミング: Pull Request（open / synchronize / reopen）
+# 実行内容:
+#   1. harness:lint  — L1 Biome AST ルール検証
+#   2. harness:ci-check — L3 CI バリデータ（security / performance / coverage / nyquist）
+#   3. 失敗時: PR にエラーサマリーをコメント
+
+name: AIDLC Quality Gate
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  harness-gate:
+    name: Harness Quality Gate
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write   # PRコメント書き込みに必要
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # L1: Biome AST ルール
+      - name: L1 Lint (Biome AST)
+        id: lint
+        run: |
+          set +e
+          RESULT=$(pnpm run harness lint --json 2>&1)
+          EXIT_CODE=$?
+          echo "result<<EOF" >> $GITHUB_OUTPUT
+          echo "$RESULT" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+          echo "exit_code=$EXIT_CODE" >> $GITHUB_OUTPUT
+          exit $EXIT_CODE
+
+      # L3: CI バリデータ（security / performance / coverage / nyquist）
+      - name: L3 CI Check
+        id: ci_check
+        if: always()
+        run: |
+          set +e
+          RESULT=$(pnpm run harness harness:ci-check --json 2>&1)
+          EXIT_CODE=$?
+          echo "result<<EOF" >> $GITHUB_OUTPUT
+          echo "$RESULT" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+          echo "exit_code=$EXIT_CODE" >> $GITHUB_OUTPUT
+          exit $EXIT_CODE
+
+      # 失敗時のみ PR にコメント
+      - name: Post failure comment
+        if: failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const lintResult   = `${{ steps.lint.outputs.result }}`;
+            const ciResult     = `${{ steps.ci_check.outputs.result }}`;
+            const lintFailed   = '${{ steps.lint.outputs.exit_code }}' !== '0';
+            const ciFailed     = '${{ steps.ci_check.outputs.exit_code }}' !== '0';
+
+            let body = '## ❌ AIDLC Quality Gate — 失敗\n\n';
+
+            if (lintFailed) {
+              body += '### L1 Lint エラー\n```json\n' + lintResult + '\n```\n\n';
+            }
+            if (ciFailed) {
+              body += '### L3 CI Check エラー\n```json\n' + ciResult + '\n```\n\n';
+            }
+
+            body += '---\n> 修正方法は各 `HarnessError.suggestion` および `HarnessError.fix_example` を参照してください。';
+
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body,
+            });

package/docs/templates/ci/consistency-check.yml

@@ -0,0 +1,117 @@
+# Phasegate — 週次整合性チェックワークフロー
+#
+# 使い方:
+#   このファイルを .github/workflows/consistency-check.yml にコピーして使用する。
+#
+# 実行タイミング: 毎週月曜 09:00 UTC（手動トリガーも可）
+# 実行内容:
+#   1. harness:detect-drift   — L4 設計⇔コード乖離検出（drift-detect）
+#   2. harness:complete-check — L4 全バリデータ（drift-detect / consistency-check / dead-code）
+#   3. 乖離検出時: GitHub Issue を自動作成
+
+name: AIDLC Consistency Check (Weekly)
+
+on:
+  schedule:
+    - cron: '0 9 * * 1'   # 毎週月曜 09:00 UTC
+  workflow_dispatch:       # 手動トリガー
+
+jobs:
+  consistency-check:
+    name: L4 Consistency & Drift Check
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write   # Issue 自動作成に必要
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # L4-001: Drift Detection（設計⇔コード双方向乖離）
+      - name: L4 Drift Detection
+        id: drift
+        run: |
+          set +e
+          RESULT=$(pnpm run harness harness:detect-drift --json 2>&1)
+          EXIT_CODE=$?
+          echo "result<<EOF" >> $GITHUB_OUTPUT
+          echo "$RESULT" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+          echo "exit_code=$EXIT_CODE" >> $GITHUB_OUTPUT
+          exit 0   # Issue作成のため常に続行
+
+      # L4: 全バリデータ（drift-detect + consistency-check + dead-code）
+      - name: L4 Complete Check
+        id: complete
+        run: |
+          set +e
+          RESULT=$(pnpm run harness harness:complete-check --json 2>&1)
+          EXIT_CODE=$?
+          echo "result<<EOF" >> $GITHUB_OUTPUT
+          echo "$RESULT" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+          echo "exit_code=$EXIT_CODE" >> $GITHUB_OUTPUT
+          exit 0   # Issue作成のため常に続行
+
+      # 乖離が検出された場合のみ Issue を作成
+      - name: Create issue on drift detected
+        if: |
+          steps.drift.outputs.exit_code != '0' ||
+          steps.complete.outputs.exit_code != '0'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const driftResult    = `${{ steps.drift.outputs.result }}`;
+            const completeResult = `${{ steps.complete.outputs.result }}`;
+            const driftFailed    = '${{ steps.drift.outputs.exit_code }}' !== '0';
+            const completeFailed = '${{ steps.complete.outputs.exit_code }}' !== '0';
+
+            const today = new Date().toISOString().slice(0, 10);
+            let body = `## 🔍 AIDLC 整合性チェック結果 — ${today}\n\n`;
+            body += '> 週次スケジュール実行により設計⇔コードの乖離が検出されました。\n\n';
+
+            if (driftFailed) {
+              body += '### L4-001 Drift Detection\n```json\n' + driftResult + '\n```\n\n';
+            }
+            if (completeFailed) {
+              body += '### L4 Complete Check\n```json\n' + completeResult + '\n```\n\n';
+            }
+
+            body += '---\n';
+            body += '### 対処方法\n';
+            body += '1. 乖離の内容を確認し、設計文書またはコードのどちらを修正すべきか判断\n';
+            body += '2. `cascade-updater` スキルで設計文書を更新、または実装を修正\n';
+            body += '3. `pnpm run harness harness:detect-drift` で再検証して乖離が解消されたことを確認\n';
+
+            github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: `[AIDLC] 設計⇔コード乖離検出 (${today})`,
+              body,
+              labels: ['aidlc', 'drift-detected', 'automated'],
+            });
+
+      - name: Summary
+        run: |
+          DRIFT_CODE="${{ steps.drift.outputs.exit_code }}"
+          COMPLETE_CODE="${{ steps.complete.outputs.exit_code }}"
+          if [ "$DRIFT_CODE" = "0" ] && [ "$COMPLETE_CODE" = "0" ]; then
+            echo "✅ 設計⇔コード整合性: 問題なし"
+          else
+            echo "❌ 乖離を検出しました。GitHub Issue を確認してください。"
+            exit 1
+          fi

package/docs/templates/hooks/commit-msg

@@ -0,0 +1,13 @@
+#!/usr/bin/env sh
+# PhaseGate commit-msg hook template.
+#
+# Usage:
+#   1. Copy this file to .husky/commit-msg
+#   2. chmod +x .husky/commit-msg
+#
+# The hook validates commit-message trailers that require access to the final
+# commit message, such as `Work-Item: WI-XXX` for WI document changes.
+
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx phasegate commit-msg "$1"

package/docs/templates/hooks/pre-commit

@@ -0,0 +1,62 @@
+#!/usr/bin/env sh
+# GSDLC Quality Harness — Pre-commit Hook テンプレート
+#
+# 使い方:
+#   1. このファイルを .husky/pre-commit にコピーする
+#   2. chmod +x .husky/pre-commit
+#   3. pnpm add --save-dev husky && npx husky install
+#
+# 実行内容:
+#   L1: Biome AST ルール（require-unit-comment, no-layer-violation など 8ルール）
+#   L2: Pre-commit バリデータ（phase-gate / metadata / test-quality）
+#
+# ⚠️  Quick Mode の場合は HARNESS_QUICK_MODE=1 を設定してコミットする:
+#   HARNESS_QUICK_MODE=1 git commit -m "fix: ..."
+
+. "$(dirname -- "$0")/_/husky.sh"
+
+HARNESS_CMD="npx tsx scripts/harness/main.ts"
+
+echo "🔍 AIDLC Quality Gate (Pre-commit)"
+echo "──────────────────────────────────"
+
+# -----------------------------------------------------------------------
+# L1: Biome AST ルール
+# -----------------------------------------------------------------------
+echo "▶ L1 Lint (Biome AST)..."
+$HARNESS_CMD lint
+L1_EXIT=$?
+
+if [ $L1_EXIT -ne 0 ]; then
+  echo ""
+  echo "❌ L1 Lint が失敗しました。"
+  echo "   修正してから再度コミットしてください。"
+  echo "   詳細: pnpm run harness lint"
+  exit 1
+fi
+echo "✅ L1 Lint: passed"
+
+# -----------------------------------------------------------------------
+# L2: Pre-commit バリデータ
+# -----------------------------------------------------------------------
+# Quick Mode では phase-gate をスキップ
+if [ "${HARNESS_QUICK_MODE:-0}" = "1" ]; then
+  echo "▶ L2 Validators (Quick Mode: phase-gate スキップ)..."
+  $HARNESS_CMD check-phase-gate --skip-phase-gate
+else
+  echo "▶ L2 Validators (phase-gate / metadata / test-quality)..."
+  $HARNESS_CMD check-phase-gate
+fi
+L2_EXIT=$?
+
+if [ $L2_EXIT -ne 0 ]; then
+  echo ""
+  echo "❌ L2 Validators が失敗しました。"
+  echo "   修正してから再度コミットしてください。"
+  echo "   詳細: pnpm run harness check-phase-gate"
+  exit 1
+fi
+echo "✅ L2 Validators: passed"
+
+echo "──────────────────────────────────"
+echo "✅ AIDLC Quality Gate: passed"

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "phasegate",
-  "version": "0.134.0",
+  "version": "0.136.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/junpei-9898/phasegate.git"
+    "url": "git+https://github.com/junpei-9898/phasegate.git"
   },
   "homepage": "https://github.com/junpei-9898/phasegate#readme",
   "bugs": {
@@ -35,14 +35,16 @@
     "skills/**",
     "templates/**",
     "docs/ADR/**",
+    "docs/contracts/**",
     "docs/principles/**",
     "docs/guide/**",
+    "docs/templates/**",
     "docs/folder_management_rules.md",
     "LICENSE",
     "CHANGELOG.md"
   ],
   "bin": {
-    "phasegate": "./bin/phasegate"
+    "phasegate": "bin/phasegate"
   },
   "scripts": {
     "phasegate": "npx tsx scripts/harness/main.ts",

package/scripts/harness/ci-governance/composition-root.ts

@@ -70,7 +70,7 @@ export function buildCiGovernance(
   const presetConfigAdapter = new PresetConfigAdapter();
   const errorRepetitionRepository = new ErrorRepetitionJsonRepository(baseDir);
   const escalationExecutorPort = new EscalationLogExecutorAdapter();
-  const templateRendererPort = new YamlTemplateRendererAdapter();
+  const templateRendererPort = new YamlTemplateRendererAdapter(harnessRoot);
   const fileExistencePort = new FileSystemExistenceAdapter(baseDir);
   const commandExistencePort = new HarnessApiCommandExistenceAdapter();
   const adrExistencePort = new AdrFoundationExistenceAdapter();

package/scripts/harness/ci-governance/infrastructure/adapters/yaml-template-renderer-adapter.ts

@@ -5,6 +5,8 @@
  * TemplateRendererPort実装（YAML書き出し）
  */
 
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import type { TemplateRendererPort, TemplateRenderOutput } from '../../domain/ports/template-renderer-port.js';
 import type { CiTemplate } from '../../domain/aggregates/ci-template.js';
 
@@ -14,40 +16,21 @@ const OUTPUT_PATH_MAP: Record<string, string> = {
   'pre-commit': '.husky/pre-commit',
 };
 
+const TEMPLATE_PATH_MAP: Record<string, string> = {
+  'aidlc-gate': 'docs/templates/ci/aidlc-gate.yml',
+  'consistency-check': 'docs/templates/ci/consistency-check.yml',
+  'pre-commit': 'docs/templates/hooks/pre-commit',
+};
+
 export class YamlTemplateRendererAdapter implements TemplateRendererPort {
+  constructor(private readonly harnessRoot: string = process.cwd()) {}
+
   async render(ciTemplate: CiTemplate): Promise<TemplateRenderOutput> {
     const outputPath = OUTPUT_PATH_MAP[ciTemplate.templateType] ?? '';
-    const content = this.generateContent(ciTemplate);
+    const templatePath = TEMPLATE_PATH_MAP[ciTemplate.templateType];
+    const content = templatePath === undefined
+      ? `# ${ciTemplate.templateType} template (not configured)`
+      : await readFile(join(this.harnessRoot, templatePath), 'utf-8');
     return { outputPath, content };
   }
-
-  private generateContent(ciTemplate: CiTemplate): string {
-    const { templateType, config } = ciTemplate;
-
-    if (!config) {
-      return `# ${templateType} template (not configured)`;
-    }
-
-    if (templateType === 'pre-commit') {
-      return [
-        '#!/bin/sh',
-        '. "$(dirname "$0")/_/husky.sh"',
-        '',
-        `npx phasegate lint --validators ${config.targetValidatorIds.join(',')}`,
-      ].join('\n');
-    }
-
-    return [
-      `name: ${templateType}`,
-      `on:`,
-      `  ${config.triggerCondition === 'pull_request' ? 'pull_request' : 'schedule'}:`,
-      config.triggerCondition === 'schedule' ? '    - cron: "0 2 * * *"' : '',
-      `jobs:`,
-      `  validate:`,
-      `    runs-on: ubuntu-latest`,
-      `    steps:`,
-      `      - uses: actions/checkout@v4`,
-      `      - run: npx phasegate lint --validators ${config.targetValidatorIds.join(',')}`,
-    ].filter((l) => l !== '').join('\n');
-  }
 }

package/scripts/harness/ci-governance/presentation/handlers/generate-ci-template-handler.ts

@@ -31,7 +31,25 @@ export class GenerateCiTemplateHandler {
   ) {}
 
   async handle(args: GenerateCiTemplateHandlerArgs): Promise<GenerateCiTemplateHandlerResult> {
-    const { presetId, templateType, format = 'human' } = args;
+    const { presetId, templateType, render = false, format = 'human' } = args;
+
+    if (render) {
+      const result = await this.renderUseCase.execute({
+        presetId,
+        templateType: templateType as TemplateType,
+      });
+      const hasErrors = result.errors.length > 0;
+      const output = format === 'json'
+        ? JSON.stringify(result, null, 2)
+        : hasErrors
+          ? result.errors.map((err) => `[${err.code}] ${err.message}`).join('\n')
+          : result.content;
+
+      return {
+        exitCode: hasErrors ? 1 : 0,
+        output,
+      };
+    }
 
     const result = await this.generateUseCase.execute({
       presetId,

package/scripts/harness/config-foundation/application/mappers/validator-system-config-mapper.ts

@@ -1,7 +1,7 @@
 /**
  * @layer application
  * @unit config-foundation
- * @work-item-id WI-092 / WI-094
+ * @work-item-id WI-092 / WI-094 / WI-033
  */
 import type { HarnessConfigV2 } from '../../domain/harness-config.js';
 
@@ -13,7 +13,7 @@ export function toValidatorSystemConfig(resolvedConfig: HarnessConfigV2 | undefi
     layers: {
       L2: { enabled: resolvedConfig.layers.L2.enabled },
       L3: { enabled: resolvedConfig.layers.L3.enabled },
-      L4: { enabled: resolvedConfig.layers.L4.enabled },
+      L4: { enabled: resolvedConfig.layers.L4.enabled, validators: resolvedConfig.layers.L4.validators },
     },
     validate: {
       failOnWarning: resolvedConfig.validate.failOnWarning,

package/scripts/harness/config-foundation/infrastructure/presets/minimal.json

@@ -15,7 +15,7 @@
     },
     "L4": {
       "enabled": false,
-      "validators": ["drift-detector"],
+      "validators": ["drift-detector", "doc-freshness-checker", "pointer-validator"],
       "schedule": "0 0 * * *"
     }
   },

package/scripts/harness/config-foundation/infrastructure/presets/standard.json

@@ -15,7 +15,7 @@
     },
     "L4": {
       "enabled": false,
-      "validators": ["drift-detector"],
+      "validators": ["drift-detector", "doc-freshness-checker", "pointer-validator"],
       "schedule": "0 0 * * *"
     }
   },

package/scripts/harness/config-foundation/infrastructure/presets/strict.json

@@ -15,7 +15,7 @@
     },
     "L4": {
       "enabled": true,
-      "validators": ["drift-detector", "dead-code-detector"],
+      "validators": ["drift-detector", "consistency-checker", "dead-code-detector", "doc-freshness-checker", "pointer-validator"],
       "schedule": "0 1 * * *"
     }
   },

package/scripts/harness/harness-error/infrastructure/adapters/validator-registry-bridge-adapter.ts

@@ -64,6 +64,8 @@ const DEFAULT_VALIDATOR_IDS = [
   'drift-detect',
   'consistency-check',
   'dead-code',
+  'doc-freshness',
+  'pointer-validation',
 ] as const;
 
 export const DEFAULT_VALIDATOR_ENTRYPOINTS = new Map<

package/scripts/harness/harness-error/infrastructure/registry/l4-error-definitions.ts

@@ -50,4 +50,18 @@ export const L4_ERROR_DEFINITIONS = Object.freeze([
     ownerValidatorId: 'dead-code',
     defaultFixExample: 'const actual = "remove unused export";',
   }),
+  createDefinition({
+    code: 'L4-004',
+    title: '設計ドキュメントの鮮度が閾値を超過した',
+    category: 'consistency',
+    ownerValidatorId: 'doc-freshness',
+    defaultFixExample: 'const actual = "review or refresh stale design document";',
+  }),
+  createDefinition({
+    code: 'L4-005',
+    title: '設計ドキュメント内のポインタ参照が解決できない',
+    category: 'consistency',
+    ownerValidatorId: 'pointer-validation',
+    defaultFixExample: 'const actual = "fix unresolved document pointer";',
+  }),
 ]);

package/scripts/harness/main.ts

@@ -41,6 +41,7 @@ import type { SkillSet } from "./setup/skill-deployer.js";
 import {
   deployAgentSkillLinks,
   deployCodexHooks,
+  deployCiWorkflows,
   deployDesignDocs,
   deployHookScripts,
   deployHuskyCommitMsgHook,
@@ -89,7 +90,7 @@ 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, --yes)
+                                --skills <core|all>, --agent <claude|codex|both>, --with-husky, --with-ci, --yes)
   update-skills                Re-deploy skills from current harness version
 
 Commands:
@@ -251,6 +252,7 @@ Options:
   --skills <core|all>             Skill set to deploy (default: "all")
   --agent <claude|codex|both>     Agent integration target (default: "claude")
   --with-husky                    Install Husky pre-commit hooks
+  --with-ci                       Install GitHub Actions workflows
   --yes                           Skip confirmation prompts
   --help, -h                      Show this help`,
   "update-skills": `Usage: phasegate update-skills [options]
@@ -636,7 +638,7 @@ async function main(): Promise<void> {
     switch (command) {
       // ── harness setup ──
       case "init": {
-        const KNOWN_INIT_FLAGS = ["--name", "--preset", "--skills", "--agent", "--with-husky", "--yes"];
+        const KNOWN_INIT_FLAGS = ["--name", "--preset", "--skills", "--agent", "--with-husky", "--with-ci", "--yes"];
         const flagError = validateKnownFlags(args, KNOWN_INIT_FLAGS);
         if (flagError) {
           console.error(flagError);
@@ -674,7 +676,8 @@ async function main(): Promise<void> {
           claude: deployClaude,
           codex: deployCodex,
         });
-        const configResult = await initHarnessConfig(rootDir, projectName, phasePreset);
+        const withCi = hasFlag(args, "--with-ci");
+        const configResult = await initHarnessConfig(rootDir, projectName, phasePreset, { ciEnabled: withCi });
         const hooksResult = deployClaude
           ? await deployHookScripts(harnessRoot, rootDir)
           : {
@@ -689,6 +692,7 @@ async function main(): Promise<void> {
         const withHusky = hasFlag(args, "--with-husky");
         const huskyResult = withHusky ? await deployHuskyHook(harnessRoot, rootDir) : null;
         const huskyCommitMsgResult = withHusky ? await deployHuskyCommitMsgHook(harnessRoot, rootDir) : null;
+        const ciWorkflowResult = withCi ? await deployCiWorkflows(harnessRoot, rootDir) : null;
         console.log(
           `✓ Skills deployed to ${result.targetDir} (${result.deployedSkills.length} skills, set: ${skillSet})`,
         );
@@ -753,6 +757,14 @@ async function main(): Promise<void> {
             console.log(`  .husky/commit-msg already exists, skipped`);
           }
         }
+        if (ciWorkflowResult !== null) {
+          if (ciWorkflowResult.copiedFiles.length > 0) {
+            console.log(`✓ CI workflows deployed (${ciWorkflowResult.copiedFiles.length} files)`);
+          }
+          for (const skipped of ciWorkflowResult.skippedFiles) {
+            console.log(`  ${skipped} already exists, skipped`);
+          }
+        }
         console.log(`✓ Harness v${result.version} initialized (agent: ${agent})`);
         console.log("");
         console.log("Next steps:");
@@ -1199,7 +1211,7 @@ Examples:
   phasegate ci:generate-template --preset strict --type pre-commit --render`);
           process.exit(0);
         }
-        const mod = buildCiGovernance(rootDir);
+        const mod = buildCiGovernance(rootDir, harnessRoot);
         const presetId = parseFlag(args, "--preset") ?? "default";
         const templateType = parseFlag(args, "--type") ?? "aidlc-gate";
         const render = hasFlag(args, "--render");
@@ -1211,7 +1223,7 @@ Examples:
       }
 
       case "ci:migrate-agents-md": {
-        const mod = buildCiGovernance(rootDir);
+        const mod = buildCiGovernance(rootDir, harnessRoot);
         const dryRun = hasFlag(args, "--dry-run");
         const validateOnly = hasFlag(args, "--validate-only");
         const format = json ? "json" : "human";
@@ -1222,7 +1234,7 @@ Examples:
       }
 
       case "ci:check-repetition": {
-        const mod = buildCiGovernance(rootDir);
+        const mod = buildCiGovernance(rootDir, harnessRoot);
         const errorCode = parseFlag(args, "--code") ?? "";
         const reset = hasFlag(args, "--reset");
         const format = json ? "json" : "human";
@@ -1233,7 +1245,7 @@ Examples:
       }
 
       case "baseline": {
-        const mod = buildCiGovernance(rootDir);
+        const mod = buildCiGovernance(rootDir, harnessRoot);
         const dryRun = hasFlag(args, "--dry-run");
         const force = hasFlag(args, "--force");
         const pathsFlag = parseFlag(args, "--paths");

package/scripts/harness/phase2-extensions/composition-root.ts

@@ -25,7 +25,13 @@ import { ValidatePointersHandler } from './presentation/handlers/validate-pointe
 
 export function buildPhase2Extensions(projectRoot: string, config?: HarnessConfigV2) {
   const configAdapter = new HarnessConfigFreshnessAdapter(config);
-  const documentScanner = new FileSystemDocumentScannerAdapter(projectRoot);
+  const inceptionDocsRoot = config?.paths?.inceptionDocs.replace(/\\/g, '/').replace(/\/+$/g, '') ?? 'docs/inception';
+  const documentScanner = new FileSystemDocumentScannerAdapter(projectRoot, {
+    excludePatterns: [
+      new RegExp(`^${inceptionDocsRoot.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/`),
+      /^docs\/.*\/archive\//,
+    ],
+  });
   const documentAge = new GitLogDocumentAgeAdapter(projectRoot);
   const pointerExtractor = new RegexPointerExtractorAdapter(projectRoot);
   const pointerResolver = new FileSystemPointerResolverAdapter(projectRoot);

package/scripts/harness/phase2-extensions/infrastructure/adapters/file-system-document-scanner-adapter.ts

@@ -6,6 +6,10 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import type { DocumentScannerPort } from '../../domain/ports/document-scanner-port.js';
 
+export interface FileSystemDocumentScannerAdapterOptions {
+  readonly excludePatterns?: readonly RegExp[];
+}
+
 function escapeRegex(value: string): string {
   return value.replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
 }
@@ -67,11 +71,21 @@ async function walk(root: string, current = ''): Promise<string[]> {
 }
 
 export class FileSystemDocumentScannerAdapter implements DocumentScannerPort {
-  constructor(private readonly projectRoot: string) {}
+  private readonly excludePatterns: readonly RegExp[];
+
+  constructor(
+    private readonly projectRoot: string,
+    options: FileSystemDocumentScannerAdapterOptions = {},
+  ) {
+    this.excludePatterns = options.excludePatterns ?? [];
+  }
 
   async scan(pattern: string): Promise<string[]> {
     const files = await walk(this.projectRoot);
     const regex = toPatternRegex(pattern);
-    return files.filter((file) => regex.test(file)).sort();
+    return files
+      .filter((file) => regex.test(file))
+      .filter((file) => !this.excludePatterns.some((excludePattern) => excludePattern.test(file)))
+      .sort();
   }
 }