@pzy560117/codex-harness 0.1.0 → 0.1.2

package/package-source/docs/codex-harness-engineering/templates/runtime/scripts/test-install-modes.ps1

@@ -0,0 +1,3 @@
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+& (Join-Path $PSScriptRoot 'test-project-root-layout.ps1')

package/package-source/docs/codex-harness-engineering/templates/runtime/scripts/validate-init-queue.ps1

@@ -0,0 +1,175 @@
+param(
+  [string]$ProjectRoot = (Get-Location).Path,
+  [string]$TaskFile = "task.json",
+  [string]$TemplateFile = "tools/harness/templates/project-task-template.json",
+  [string]$VerifyMatrixFile = "docs\testing\verify-matrix.md"
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+function Assert-Condition {
+  param(
+    [bool]$Condition,
+    [string]$Message
+  )
+
+  if (-not $Condition) {
+    throw $Message
+  }
+}
+
+function Get-JsonDocument {
+  param([string]$Path)
+
+  Assert-Condition -Condition (Test-Path -LiteralPath $Path) -Message "文件不存在: $Path"
+  $content = Get-Content -LiteralPath $Path -Raw -Encoding UTF8
+  Assert-Condition -Condition (-not [string]::IsNullOrWhiteSpace($content)) -Message "文件为空: $Path"
+  return ($content | ConvertFrom-Json)
+}
+
+function ConvertTo-StringArray {
+  param([object]$Value)
+
+  if ($null -eq $Value) {
+    return @()
+  }
+
+  if ($Value -is [string]) {
+    if ([string]::IsNullOrWhiteSpace($Value)) {
+      return @()
+    }
+
+    return @($Value)
+  }
+
+  $items = @()
+  foreach ($item in $Value) {
+    if ($null -ne $item) {
+      $items += [string]$item
+    }
+  }
+
+  return $items
+}
+
+function Test-ExactArray {
+  param(
+    [string[]]$Actual,
+    [string[]]$Expected
+  )
+
+  if ($Actual.Count -ne $Expected.Count) {
+    return $false
+  }
+
+  for ($index = 0; $index -lt $Expected.Count; $index++) {
+    if ($Actual[$index] -ne $Expected[$index]) {
+      return $false
+    }
+  }
+
+  return $true
+}
+
+function Test-ContainsPath {
+  param(
+    [object]$Task,
+    [string]$RequiredPath
+  )
+
+  $normalizedRequiredPath = $RequiredPath.Replace("/", "\")
+  $normalizedContextPaths = @(ConvertTo-StringArray -Value $Task.context_files | ForEach-Object { ([string]$_).Replace("/", "\") })
+  return $normalizedContextPaths -contains $normalizedRequiredPath
+}
+
+function Assert-TaskExists {
+  param(
+    [hashtable]$TaskMap,
+    [string]$TaskId
+  )
+
+  Assert-Condition -Condition $TaskMap.ContainsKey($TaskId) -Message "task.json 缺少任务: $TaskId"
+}
+
+$resolvedProjectRoot = (Resolve-Path -LiteralPath $ProjectRoot).Path
+$taskPath = Join-Path $resolvedProjectRoot $TaskFile
+$templatePath = Join-Path $resolvedProjectRoot $TemplateFile
+$verifyMatrixPath = Join-Path $resolvedProjectRoot $VerifyMatrixFile
+
+$taskDocument = Get-JsonDocument -Path $taskPath
+$templateDocument = Get-JsonDocument -Path $templatePath
+
+$normalizedTask = $taskDocument | ConvertTo-Json -Depth 20
+$normalizedTemplate = $templateDocument | ConvertTo-Json -Depth 20
+Assert-Condition -Condition ($normalizedTask -eq $normalizedTemplate) -Message "task.json 与 tools/harness/templates/project-task-template.json 不一致。请先同步标准入口模板。"
+
+$taskMap = @{}
+foreach ($task in @($taskDocument.tasks)) {
+  $taskMap[[string]$task.id] = $task
+  Assert-Condition -Condition (-not ([string]$task.id).StartsWith("SMOKE", [System.StringComparison]::OrdinalIgnoreCase)) -Message "正式任务队列中仍包含 SMOKE 任务: $($task.id)"
+}
+
+$expectedDirtyPaths = @("progress.txt", "traces/")
+$actualDirtyPaths = ConvertTo-StringArray -Value $taskDocument.runtime.git.non_blocking_dirty_paths
+Assert-Condition -Condition (Test-ExactArray -Actual $actualDirtyPaths -Expected $expectedDirtyPaths) -Message "runtime.git.non_blocking_dirty_paths 必须精确等于: progress.txt, traces/"
+
+Assert-Condition -Condition (Test-Path -LiteralPath $verifyMatrixPath) -Message "缺少 verify matrix: $verifyMatrixPath"
+$verifyMatrixText = Get-Content -LiteralPath $verifyMatrixPath -Raw -Encoding UTF8
+$requiredVerifyPhrases = @(
+  "handoff / analysis / design / plan 当前只跑文档级验证",
+  "runtime preflight 由 driver 负责",
+  "PLAN-001 负责把实现阶段验证替换成真实命令",
+  "scripts/validate-queue-placeholders.ps1"
+)
+foreach ($phrase in $requiredVerifyPhrases) {
+  Assert-Condition -Condition ($verifyMatrixText.Contains($phrase)) -Message "verify-matrix 缺少关键边界说明: $phrase"
+}
+
+foreach ($taskId in @("INIT-001", "ANALYSIS-001", "DESIGN-001", "PLAN-001")) {
+  Assert-TaskExists -TaskMap $taskMap -TaskId $taskId
+}
+
+$initTask = $taskMap["INIT-001"]
+Assert-Condition -Condition ([string]$initTask.phase -eq "handoff") -Message "INIT-001.phase 必须为 handoff"
+Assert-Condition -Condition (@(ConvertTo-StringArray -Value $initTask.dependencies).Count -eq 0) -Message "INIT-001 不能依赖其他任务"
+Assert-Condition -Condition (Test-ExactArray -Actual (ConvertTo-StringArray -Value $initTask.required_truth_sources) -Expected @("plan")) -Message "INIT-001.required_truth_sources 必须只依赖 plan"
+Assert-Condition -Condition ([string]$initTask.test_command -match 'scripts\\validate-init-queue\.ps1') -Message "INIT-001.test_command 必须使用 scripts/validate-init-queue.ps1"
+foreach ($requiredPath in @("AGENTS.md", "task.json", "tools/harness/templates/project-task-template.json", "docs\context\dev-plan.md", "docs\testing\verify-matrix.md")) {
+  Assert-Condition -Condition (Test-ContainsPath -Task $initTask -RequiredPath $requiredPath) -Message "INIT-001.context_files 缺少: $requiredPath"
+}
+
+$analysisTask = $taskMap["ANALYSIS-001"]
+Assert-Condition -Condition ([string]$analysisTask.phase -eq "analysis") -Message "ANALYSIS-001.phase 必须为 analysis"
+Assert-Condition -Condition (Test-ExactArray -Actual (ConvertTo-StringArray -Value $analysisTask.dependencies) -Expected @("INIT-001")) -Message "ANALYSIS-001 必须只依赖 INIT-001"
+
+$designTask = $taskMap["DESIGN-001"]
+Assert-Condition -Condition ([string]$designTask.phase -eq "design") -Message "DESIGN-001.phase 必须为 design"
+Assert-Condition -Condition (Test-ExactArray -Actual (ConvertTo-StringArray -Value $designTask.dependencies) -Expected @("ANALYSIS-001")) -Message "DESIGN-001 必须只依赖 ANALYSIS-001"
+Assert-Condition -Condition (-not ((ConvertTo-StringArray -Value $designTask.required_truth_sources) -contains "design")) -Message "DESIGN-001 不能把 design 配成前置 truth source"
+Assert-Condition -Condition (Test-ContainsPath -Task $designTask -RequiredPath "docs\context\dev-plan.md") -Message "DESIGN-001.context_files 必须包含 docs/context/dev-plan.md"
+
+$planTask = $taskMap["PLAN-001"]
+Assert-Condition -Condition ([string]$planTask.phase -eq "plan") -Message "PLAN-001.phase 必须为 plan"
+Assert-Condition -Condition (Test-ExactArray -Actual (ConvertTo-StringArray -Value $planTask.dependencies) -Expected @("DESIGN-001")) -Message "PLAN-001 必须只依赖 DESIGN-001"
+Assert-Condition -Condition (-not ((ConvertTo-StringArray -Value $planTask.required_truth_sources) -contains "plan")) -Message "PLAN-001 不能把 plan 配成前置 truth source"
+
+$placeholderPhases = @("foundation", "domain", "verify")
+foreach ($task in @($taskDocument.tasks | Where-Object { $placeholderPhases -contains [string]$_.phase })) {
+  $expectedCommandPattern = [regex]::Escape("scripts\validate-queue-placeholders.ps1") + ".*" + [regex]::Escape($task.id)
+  Assert-Condition -Condition ([string]$task.test_command -match $expectedCommandPattern) -Message "$($task.id).test_command 仍未绑定 placeholder sentinel 或 TaskId 不匹配"
+  Assert-Condition -Condition (Test-ContainsPath -Task $task -RequiredPath "docs\context\dev-plan.md") -Message "$($task.id).context_files 必须包含 docs/context/dev-plan.md"
+}
+
+Push-Location $resolvedProjectRoot
+try {
+  $diffOutput = & git diff --check 2>&1
+  if ($LASTEXITCODE -ne 0) {
+    throw "git diff --check 失败:`n$($diffOutput -join "`n")"
+  }
+}
+finally {
+  Pop-Location
+}
+
+Write-Output "INIT queue contract validation passed."

package/package-source/docs/codex-harness-engineering/templates/runtime/scripts/validate-queue-placeholders.ps1

@@ -0,0 +1,23 @@
+param(
+  [string]$TaskId = "",
+  [string]$ProjectRoot = (Get-Location).Path
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$taskLabel = if ([string]::IsNullOrWhiteSpace($TaskId)) { "当前实现任务" } else { $TaskId }
+
+throw @"
+$taskLabel 仍在使用默认占位验证 `scripts/validate-queue-placeholders.ps1`。
+这表示 PLAN-001 还没有把实现阶段 test_command 重写成真实项目命令。
+
+需要至少补齐与 verify-matrix 一致的真实命令，例如:
+- lint
+- typecheck
+- unit / integration test
+- build
+- E2E / visual parity
+
+完成重写后，再重新运行 tools/harness/codex-loop.ps1。
+"@

package/package-source/docs/codex-harness-engineering/templates/runtime/smoke-task.json

@@ -0,0 +1,52 @@
+{
+  "tasks": [
+    {
+      "id": "SMOKE-001",
+      "description": "创建 smoke 结果文件并验证内层 Codex 会话输出边界",
+      "task_kind": "smoke",
+      "gate_profile": "lightweight",
+      "required_truth_sources": [],
+      "priority": 1,
+      "dependencies": [],
+      "passes": false,
+      "context_files": [
+        "AGENTS.md"
+      ],
+      "execution": {
+        "session": {
+          "mode": "fresh-process"
+        },
+        "subagents": {
+          "mode": "off"
+        }
+      },
+      "steps": [
+        "阅读当前仓库的 AGENTS.md",
+        "新建 SMOKE-RESULT.md",
+        "在文件中写入三条简短内容：本仓库是 Codex Harness smoke test；当前任务由内层 Codex 自动实现会话生成结果文件；本次 smoke 仅新增 SMOKE-RESULT.md",
+        "不要修改其他文件",
+        "完成后总结本次修改"
+      ],
+      "test_command": "if (-not (Test-Path -LiteralPath 'SMOKE-RESULT.md')) { exit 1 }; $lines = @(Get-Content -LiteralPath 'SMOKE-RESULT.md'); if ($lines.Count -ne 3) { exit 1 }; foreach ($line in $lines) { if ($line -match '\\s+$') { exit 1 } }; $content = [string]::Join([Environment]::NewLine, $lines); if ($content -notmatch 'Codex Harness smoke test') { exit 1 }; if ($content -notmatch '内层 Codex 自动实现会话生成结果文件') { exit 1 }; if ($content -notmatch '本次 smoke 仅新增 SMOKE-RESULT.md') { exit 1 }; $statusLines = @(git status --short --untracked-files=all); if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }; $changedPaths = @(); foreach ($line in $statusLines) { if (-not [string]::IsNullOrWhiteSpace($line) -and $line.Length -ge 4) { $changedPaths += $line.Substring(3).Trim() } }; if ($changedPaths.Count -ne 1 -or $changedPaths[0] -ne 'SMOKE-RESULT.md') { exit 1 }; git diff --check; exit $LASTEXITCODE",
+      "acceptance": [
+        "SMOKE-RESULT.md 存在",
+        "SMOKE-RESULT.md 明确说明结果文件由内层 Codex 自动实现会话生成",
+        "SMOKE-RESULT.md 明确说明本次 smoke 仅新增 SMOKE-RESULT.md",
+        "内层会话没有修改 task.json、progress.txt 或 traces/"
+      ]
+    }
+  ],
+  "runtime": {
+    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/codex-loop.ps1",
+    "run_profile": ".codex\\task-run-profile.json",
+    "session": {
+      "mode": "fresh-process",
+      "carry_forward_summary": false
+    },
+    "subagents": {
+      "mode": "off",
+      "allowed_roles": [],
+      "max_parallel_roles": 0
+    }
+  }
+}

package/package-source/docs/codex-harness-engineering/templates/runtime/task-run-profile.json

@@ -0,0 +1,86 @@
+{
+  "session": {
+    "mode": "fresh-process",
+    "reuse_previous_chat": false,
+    "carry_forward_summary": false,
+    "context_sources": [
+      "AGENTS.md",
+      "docs/harness/task-session-strategy.md",
+      "docs/harness/architecture.md",
+      "docs/harness/knowledge-architecture.md",
+      "docs/harness/prompt-knowledge-integration.md",
+      "docs/harness/rule-governance.md",
+      "docs/harness/regression-rules.md",
+      "docs/knowledge/knowledge-catalog.md",
+      "docs/testing/ACCEPTANCE_EXAMPLES.md",
+      "docs/testing/TRACEABILITY_MATRIX.md",
+      "docs/testing/TEST_STRATEGY.md",
+      "docs/testing/TEST_DATA_MATRIX.md",
+      "docs/testing/RISK_BASED_TEST_PLAN.md",
+      "docs/testing/EVIDENCE_PROTOCOL.md",
+      "docs/testing/test-matrix.md",
+      "docs/testing/verify-matrix.md"
+    ]
+  },
+  "subagents": {
+    "mode": "guided",
+    "allowed_roles": [
+      "explorer",
+      "readonly-research",
+      "docs-researcher",
+      "planner",
+      "architect",
+      "reviewer",
+      "stage1-reviewer",
+      "stage2-reviewer",
+      "security-reviewer",
+      "test-planner",
+      "failure-triage",
+      "visual-reviewer",
+      "harness-writer",
+      "docs-worker",
+      "frontend-worker",
+      "backend-worker",
+      "test-runner"
+    ],
+    "max_parallel_roles": 3,
+    "notes": [
+      "Implementation sessions may use subagents to accelerate development when work can be split by ownership, role, or verification boundary.",
+      "Subagents must read the matching AGENTS/rules/docs/skills before concluding.",
+      "Read-only roles stay read-only and return summaries or concrete results, not full transcripts.",
+      "Writer roles must receive explicit allowed paths, forbidden paths, expected output, and verification commands before editing.",
+      "Any repo write outside driver-owned runtime outputs must go to a matching writer role; the controller/main session should not write directly."
+    ]
+  },
+  "modelPolicy": {
+    "defaultModel": "gpt-5.4",
+    "defaultReasoningEffort": "medium",
+    "reasoningEfforts": [
+      "none",
+      "low",
+      "medium",
+      "high",
+      "xhigh"
+    ],
+    "overrideOrder": [
+      "task.execution.modelPolicy",
+      "modelPolicy.default"
+    ],
+    "escalation": {
+      "sameFindingRetry2": {
+        "model": "gpt-5.5",
+        "reasoningEffort": "high"
+      },
+      "sameFindingRetry3": {
+        "model": "gpt-5.5",
+        "reasoningEffort": "xhigh"
+      }
+    }
+  },
+  "workspace": {
+    "mode": "in-place"
+  },
+  "git": {
+    "require_clean_workspace": true
+  }
+}

package/package-source/docs/codex-harness-engineering/templates/runtime/task.json

@@ -0,0 +1,49 @@
+{
+  "runtime": {
+    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/codex-loop.ps1",
+    "trace_dir": "traces",
+    "agent": "codex",
+    "run_profile": ".codex\\task-run-profile.json",
+    "git": {
+      "require_clean_workspace": true,
+      "non_blocking_dirty_paths": []
+    },
+    "session": {
+      "mode": "fresh-process",
+      "carry_forward_summary": false
+    },
+    "state_compaction": {
+      "enabled": true,
+      "archive_completed_tasks": true,
+      "completed_task_retention": 5,
+      "task_archive_dir": "archive/tasks",
+      "rotate_progress": true,
+      "progress_max_lines": 300,
+      "progress_archive_dir": "progress/archive"
+    },
+    "subagents": {
+      "mode": "guided",
+      "allowed_roles": [
+        "explorer",
+        "readonly-research",
+        "docs-researcher",
+        "planner",
+        "architect",
+        "reviewer",
+        "stage1-reviewer",
+        "stage2-reviewer",
+        "security-reviewer",
+        "test-planner",
+        "failure-triage",
+        "visual-reviewer",
+        "harness-writer",
+        "docs-worker",
+        "frontend-worker",
+        "backend-worker",
+        "test-runner"
+      ],
+      "max_parallel_roles": 3
+    }
+  },
+  "tasks": []
+}

package/package-source/docs/codex-harness-engineering/templates/runtime/verify.ps1

@@ -0,0 +1,285 @@
+param(
+  [string]$ProjectRoot = "",
+  [string[]]$Commands = @("git diff --check"),
+  [string[]]$HookConfigPaths = @()
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+if ([string]::IsNullOrWhiteSpace($ProjectRoot)) {
+  $ProjectRoot = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot "..\.."))
+}
+
+function Invoke-VerificationCommand {
+  param(
+    [string]$Command,
+    [string]$Root
+  )
+
+  Push-Location $Root
+  try {
+    Write-Output "Running: $Command"
+    powershell -NoProfile -Command $Command
+    if ($LASTEXITCODE -ne 0) {
+      throw "验证失败，退出码 $($LASTEXITCODE): $Command"
+    }
+  }
+  finally {
+    Pop-Location
+  }
+}
+
+function Get-CodexHookCommand {
+  param(
+    [object]$Node,
+    [string]$Path = "$"
+  )
+
+  if ($null -eq $Node -or $Node -is [string]) {
+    return
+  }
+
+  if ($Node -is [System.Collections.IEnumerable] -and $Node -isnot [System.Collections.IDictionary]) {
+    $index = 0
+    foreach ($item in $Node) {
+      Get-CodexHookCommand -Node $item -Path "${Path}[$index]"
+      $index += 1
+    }
+    return
+  }
+
+  foreach ($property in $Node.PSObject.Properties) {
+    $childPath = "$Path.$($property.Name)"
+    if ($property.Name -eq "command" -and $property.Value -is [string]) {
+      [pscustomobject]@{
+        Path = $childPath
+        Command = $property.Value
+      }
+    }
+
+    Get-CodexHookCommand -Node $property.Value -Path $childPath
+  }
+}
+
+function Get-CandidateHookConfigPaths {
+  param(
+    [string]$Root,
+    [string[]]$AdditionalPaths
+  )
+
+  return @(
+    (Join-Path $HOME ".codex\hooks.json"),
+    (Join-Path $Root ".codex\hooks.json"),
+    (Join-Path $Root "docs\codex-harness-engineering\templates\hooks\hooks.json")
+  ) + $AdditionalPaths
+}
+
+function Resolve-HookScriptReference {
+  param(
+    [string]$Root,
+    [string]$Command
+  )
+
+  $expanded = $Command.Replace('$(git rev-parse --show-toplevel)', $Root.Replace('\', '/'))
+  $scriptPath = $null
+
+  if ($expanded -match "Join-Path[\s\S]*?['""]([^'""]*hook-stop-verify\.ps1)['""]") {
+    $scriptPath = Join-Path $Root $Matches[1]
+  }
+  elseif ($expanded -match '"([^"]*hook-stop-verify\.ps1)"') {
+    $scriptPath = $Matches[1]
+  }
+  elseif ($expanded -match '(\S*hook-stop-verify\.ps1)') {
+    $scriptPath = $Matches[1]
+  }
+
+  if ([string]::IsNullOrWhiteSpace($scriptPath)) {
+    return $null
+  }
+
+  $scriptPath = $scriptPath.Replace('/', '\')
+  if ([System.IO.Path]::IsPathRooted($scriptPath)) {
+    return $scriptPath
+  }
+
+  return (Join-Path $Root $scriptPath)
+}
+
+function Test-HookScriptInstallMapping {
+  param(
+    [string]$Root,
+    [string]$ResolvedScriptPath
+  )
+
+  if (Test-Path -LiteralPath $ResolvedScriptPath) {
+    return $true
+  }
+
+  $relativeExpectedPath = "tools\harness\hook-stop-verify.ps1"
+  $normalized = $ResolvedScriptPath.Replace("/", "\")
+  if (-not $normalized.EndsWith($relativeExpectedPath, [System.StringComparison]::OrdinalIgnoreCase)) {
+    return $false
+  }
+
+  $templateScript = Join-Path $Root "docs\codex-harness-engineering\templates\hooks\hook-stop-verify.ps1"
+  $bootstrapScript = Join-Path $Root "tools\install\bootstrap-codex-harness.ps1"
+  if (-not ((Test-Path -LiteralPath $templateScript) -and (Test-Path -LiteralPath $bootstrapScript))) {
+    return $false
+  }
+
+  $bootstrapText = Get-Content -LiteralPath $bootstrapScript -Raw
+  return $bootstrapText.Contains('hooks\hook-stop-verify.ps1') -and $bootstrapText.Contains('tools\harness\hook-stop-verify.ps1')
+}
+
+function Test-CodexHookCommandCompatibility {
+  param(
+    [string]$Root,
+    [string[]]$AdditionalPaths
+  )
+
+  $seen = @{}
+  foreach ($path in Get-CandidateHookConfigPaths -Root $Root -AdditionalPaths $AdditionalPaths) {
+    if ([string]::IsNullOrWhiteSpace($path) -or $seen.ContainsKey($path)) {
+      continue
+    }
+    $seen[$path] = $true
+
+    if (-not (Test-Path -LiteralPath $path)) {
+      continue
+    }
+
+    $hookConfig = Get-Content -LiteralPath $path -Raw | ConvertFrom-Json
+    foreach ($entry in Get-CodexHookCommand -Node $hookConfig) {
+      if ($entry.Command -match '^\s*"[^"]*\\PowerShell\\[^"]*\\pwsh(?:\.exe)?"\s+') {
+        throw "高风险 Codex hook command: $path $($entry.Path)。带空格的 quoted PowerShell executable 在 PowerShell 外层解释时会被当作字符串。请改用 pwsh、C:\Progra~1\PowerShell\7\pwsh.exe，或在确认外层是 PowerShell 时使用 & 调用。"
+      }
+
+      $scriptReference = Resolve-HookScriptReference -Root $Root -Command $entry.Command
+      if ($null -ne $scriptReference -and -not (Test-HookScriptInstallMapping -Root $Root -ResolvedScriptPath $scriptReference)) {
+        throw "Codex hook command 指向的脚本不可解析或未被 bootstrap 安装: $path $($entry.Path) -> $scriptReference"
+      }
+    }
+  }
+}
+
+function Test-PowerShellSyntax {
+  param([string]$Root)
+
+  $paths = @(
+    "tools\install\bootstrap-codex-harness.ps1",
+    "tools\harness\codex-loop.ps1",
+    "tools\install\env-check.ps1",
+    "tools\install\install-agent.ps1",
+    "tools\install\install-agent-here.ps1",
+    "tools\harness\verify.ps1",
+    "docs\codex-harness-engineering\templates\bootstrap-codex-harness.ps1",
+    "docs\codex-harness-engineering\templates\hooks\hook-stop-verify.ps1"
+  )
+
+  foreach ($relativePath in $paths) {
+    $path = Join-Path $Root $relativePath
+    if (-not (Test-Path -LiteralPath $path)) {
+      continue
+    }
+
+    $tokens = $null
+    $errors = $null
+    [System.Management.Automation.Language.Parser]::ParseFile($path, [ref]$tokens, [ref]$errors) | Out-Null
+    if ($errors.Count -gt 0) {
+      $messages = ($errors | ForEach-Object { $_.Message }) -join "; "
+      throw "PowerShell 语法检查失败: $relativePath - $messages"
+    }
+  }
+}
+
+function Get-RelativePathCompat {
+  param(
+    [string]$Root,
+    [string]$Path
+  )
+
+  $rootFull = ([System.IO.Path]::GetFullPath($Root)).TrimEnd('\', '/') + '\'
+  $pathFull = [System.IO.Path]::GetFullPath($Path)
+  if ($pathFull.StartsWith($rootFull, [System.StringComparison]::OrdinalIgnoreCase)) {
+    return $pathFull.Substring($rootFull.Length)
+  }
+
+  return $pathFull
+}
+
+function Test-NoStaleFeedbackMcpReferences {
+  param([string]$Root)
+
+  $scanRoots = @(
+    "docs\harness",
+    "docs\codex-harness-engineering"
+  )
+
+  $blockedPatterns = @(
+    "interactive_feedback",
+    "mcp-feedback-enhanced"
+  )
+
+  foreach ($scanRoot in $scanRoots) {
+    $fullScanRoot = Join-Path $Root $scanRoot
+    if (-not (Test-Path -LiteralPath $fullScanRoot)) {
+      continue
+    }
+
+    foreach ($file in Get-ChildItem -LiteralPath $fullScanRoot -Recurse -File -Include *.md,*.toml,*.json,*.ps1) {
+      $relativePath = Get-RelativePathCompat -Root $Root -Path $file.FullName
+      if ($relativePath.EndsWith("templates\runtime\verify.ps1", [System.StringComparison]::OrdinalIgnoreCase)) {
+        continue
+      }
+
+      $content = Get-Content -LiteralPath $file.FullName -Raw
+      $text = if ($null -eq $content) { "" } else { [string]$content }
+      foreach ($pattern in $blockedPatterns) {
+        if ($text.Contains($pattern)) {
+          throw "发现已移除的 feedback MCP 引用: $relativePath contains '$pattern'"
+        }
+      }
+    }
+  }
+}
+
+function Invoke-AgentPackageFreshnessCheck {
+  param([string]$Root)
+
+  $packageRoot = $Root
+  $repoCandidate = Split-Path -Parent $packageRoot
+  $packageConfig = Join-Path $packageRoot ".ai-sync.yml"
+  $refreshScript = Join-Path $repoCandidate "refresh-agent-package.ps1"
+  $packageSourceMarker = Join-Path $repoCandidate "docs\codex-harness-engineering\templates\package-assets\root\install-agent.ps1"
+
+  if (-not (Test-Path -LiteralPath $packageConfig -PathType Leaf)) {
+    return
+  }
+
+  if (-not (Test-Path -LiteralPath $packageSourceMarker -PathType Leaf)) {
+    return
+  }
+
+  if (-not (Test-Path -LiteralPath $refreshScript -PathType Leaf)) {
+    throw "缺少 refresh-agent-package.ps1，无法校验 agent package freshness。"
+  }
+
+  & powershell -NoProfile -ExecutionPolicy Bypass -File $refreshScript -RepoRoot $repoCandidate -PackageRoot $packageRoot -CheckOnly | Out-Host
+  if ($LASTEXITCODE -ne 0) {
+    throw "agent package freshness 检查失败。"
+  }
+}
+
+$resolvedProjectRoot = (Resolve-Path -LiteralPath $ProjectRoot).Path
+
+foreach ($command in $Commands) {
+  Invoke-VerificationCommand -Command $command -Root $resolvedProjectRoot
+}
+
+Test-CodexHookCommandCompatibility -Root $resolvedProjectRoot -AdditionalPaths $HookConfigPaths
+Test-PowerShellSyntax -Root $resolvedProjectRoot
+Test-NoStaleFeedbackMcpReferences -Root $resolvedProjectRoot
+Invoke-AgentPackageFreshnessCheck -Root $resolvedProjectRoot
+
+Write-Output "Verification passed."