@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/tools/harness/context-lint.ps1

@@ -0,0 +1,187 @@
+param(
+  [string]$ProjectRoot = "",
+  [switch]$AsJson,
+  [switch]$AllowWarningsOnly
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+if ([string]::IsNullOrWhiteSpace($ProjectRoot)) {
+  $ProjectRoot = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot "..\.."))
+}
+
+function New-Issue {
+  param(
+    [string]$Severity,
+    [string]$File,
+    [string]$Section,
+    [string]$Message
+  )
+
+  [PSCustomObject]@{
+    severity = $Severity
+    file = $File
+    section = $Section
+    message = $Message
+  }
+}
+
+function Get-FileContentOrNull {
+  param([string]$Path)
+
+  if (-not (Test-Path -LiteralPath $Path)) {
+    return $null
+  }
+
+  Get-Content -LiteralPath $Path -Raw
+}
+
+function Test-ContainsPlaceholder {
+  param([string]$Content)
+
+  if ([string]::IsNullOrWhiteSpace($Content)) {
+    return $false
+  }
+
+  return (
+    $Content -match '(?im)\bTBD\b' -or
+    $Content -match '(?im)\bTODO\b' -or
+    $Content -match '(?im)<replace-'
+  )
+}
+
+function Test-ContainsAny {
+  param(
+    [string]$Content,
+    [string[]]$Terms
+  )
+
+  foreach ($term in $Terms) {
+    if ($Content -match [regex]::Escape($term)) {
+      return $true
+    }
+  }
+
+  return $false
+}
+
+function Test-ContainsAll {
+  param(
+    [string]$Content,
+    [string[]]$Terms
+  )
+
+  foreach ($term in $Terms) {
+    if ($Content -notmatch [regex]::Escape($term)) {
+      return $false
+    }
+  }
+
+  return $true
+}
+
+$issues = @()
+
+$repoMapPath = Join-Path $ProjectRoot "docs\ai\repo-map.md"
+$currentTaskPath = Join-Path $ProjectRoot "docs\ai\CURRENT_TASK.md"
+$apiMapPath = Join-Path $ProjectRoot "docs\ai\API_MAP.md"
+$dbSchemaPath = Join-Path $ProjectRoot "docs\ai\DB_SCHEMA.md"
+$architectureBriefPath = Join-Path $ProjectRoot "docs\ai\architecture-brief.md"
+
+$repoMap = Get-FileContentOrNull -Path $repoMapPath
+$currentTask = Get-FileContentOrNull -Path $currentTaskPath
+$apiMap = Get-FileContentOrNull -Path $apiMapPath
+$dbSchema = Get-FileContentOrNull -Path $dbSchemaPath
+$architectureBrief = Get-FileContentOrNull -Path $architectureBriefPath
+
+if ($null -eq $repoMap) {
+  $issues += New-Issue -Severity "error" -File "docs/ai/repo-map.md" -Section "file" -Message "缺少 repo-map 导航入口。"
+}
+else {
+  if (Test-ContainsPlaceholder -Content $repoMap) {
+    $issues += New-Issue -Severity "error" -File "docs/ai/repo-map.md" -Section "placeholders" -Message "repo-map 仍包含占位符，代码导航事实未收敛。"
+  }
+  if (-not (Test-ContainsAll -Content $repoMap -Terms @("关键目录", "从哪里开始读", "常用命令"))) {
+    $issues += New-Issue -Severity "error" -File "docs/ai/repo-map.md" -Section "minimum-sections" -Message "repo-map 缺少关键目录、阅读顺序或常用命令。"
+  }
+  if (-not (Test-ContainsAll -Content $repoMap -Terms @("入口", "调用链", "测试"))) {
+    $issues += New-Issue -Severity "warning" -File "docs/ai/repo-map.md" -Section "code-navigation" -Message "repo-map 未明确入口、调用链或测试入口，难以支撑第二章的上下文定位。"
+  }
+}
+
+if ($null -eq $architectureBrief) {
+  $issues += New-Issue -Severity "warning" -File "docs/ai/architecture-brief.md" -Section "file" -Message "缺少 architecture-brief，模块级导航摘要不完整。"
+}
+elseif (Test-ContainsPlaceholder -Content $architectureBrief) {
+  $issues += New-Issue -Severity "warning" -File "docs/ai/architecture-brief.md" -Section "placeholders" -Message "architecture-brief 仍包含占位符。"
+}
+
+if ($null -eq $currentTask) {
+  $issues += New-Issue -Severity "error" -File "docs/ai/CURRENT_TASK.md" -Section "file" -Message "缺少 CURRENT_TASK 当前任务导航文件。"
+}
+else {
+  if (-not (Test-ContainsAll -Content $currentTask -Terms @("任务目标", "验收标准", "owned paths", "风险点", "依赖的真相源", "关键验证命令", "暂时不要动的区域"))) {
+    $issues += New-Issue -Severity "error" -File "docs/ai/CURRENT_TASK.md" -Section "minimum-fields" -Message "CURRENT_TASK 缺少任务目标、验收、owned paths、风险点、真相源、验证命令或 no-touch 区域。"
+  }
+  if (Test-ContainsPlaceholder -Content $currentTask) {
+    $issues += New-Issue -Severity "warning" -File "docs/ai/CURRENT_TASK.md" -Section "placeholders" -Message "CURRENT_TASK 仍包含占位符，当前任务上下文可能未刷新。"
+  }
+}
+
+if ($null -eq $apiMap) {
+  $issues += New-Issue -Severity "warning" -File "docs/ai/API_MAP.md" -Section "file" -Message "缺少 API_MAP；如果项目有接口、路由或命令入口，应补齐。"
+}
+else {
+  if (Test-ContainsPlaceholder -Content $apiMap) {
+    $issues += New-Issue -Severity "warning" -File "docs/ai/API_MAP.md" -Section "placeholders" -Message "API_MAP 仍包含占位符。"
+  }
+  if (-not (Test-ContainsAny -Content $apiMap -Terms @("命令入口", "路由", "接口", "配置接口"))) {
+    $issues += New-Issue -Severity "warning" -File "docs/ai/API_MAP.md" -Section "entrypoints" -Message "API_MAP 未明确对外入口类型。"
+  }
+}
+
+if ($null -eq $dbSchema) {
+  $issues += New-Issue -Severity "warning" -File "docs/ai/DB_SCHEMA.md" -Section "file" -Message "缺少 DB_SCHEMA；如果项目有数据模型或持久化边界，应补齐。"
+}
+else {
+  if (Test-ContainsPlaceholder -Content $dbSchema) {
+    $issues += New-Issue -Severity "warning" -File "docs/ai/DB_SCHEMA.md" -Section "placeholders" -Message "DB_SCHEMA 仍包含占位符。"
+  }
+}
+
+$errors = @($issues | Where-Object { $_.severity -eq "error" })
+$warnings = @($issues | Where-Object { $_.severity -eq "warning" })
+$exitCode = if ($errors.Count -gt 0) { 1 } elseif ($warnings.Count -gt 0 -and -not $AllowWarningsOnly) { 2 } else { 0 }
+
+if ($AsJson) {
+  [PSCustomObject]@{
+    ok = ($exitCode -eq 0)
+    errors = $errors
+    warnings = $warnings
+  } | ConvertTo-Json -Depth 6
+  exit $exitCode
+}
+
+if ($errors.Count -eq 0 -and $warnings.Count -eq 0) {
+  Write-Output "Context lint passed."
+  exit 0
+}
+
+if ($errors.Count -gt 0) {
+  Write-Output "Context lint failed."
+  foreach ($issue in $errors) {
+    Write-Output ("- [ERROR] {0} :: {1} :: {2}" -f $issue.file, $issue.section, $issue.message)
+  }
+}
+
+if ($warnings.Count -gt 0) {
+  if ($errors.Count -eq 0) {
+    Write-Output "Context lint passed with warnings."
+  }
+  foreach ($issue in $warnings) {
+    Write-Output ("- [WARNING] {0} :: {1} :: {2}" -f $issue.file, $issue.section, $issue.message)
+  }
+}
+
+exit $exitCode

package/package-source/docs/codex-harness-engineering/templates/tools/harness/contract-lint.ps1

@@ -0,0 +1,148 @@
+param(
+  [string]$ProjectRoot = "",
+  [switch]$AsJson,
+  [switch]$AllowWarningsOnly
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+if ([string]::IsNullOrWhiteSpace($ProjectRoot)) {
+  $ProjectRoot = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot "..\..\..\.."))
+}
+
+function New-Issue {
+  param(
+    [string]$Severity,
+    [string]$File,
+    [string]$Section,
+    [string]$Message
+  )
+
+  [PSCustomObject]@{
+    severity = $Severity
+    file = $File
+    section = $Section
+    message = $Message
+  }
+}
+
+function Get-FileContentOrNull {
+  param([string]$Path)
+
+  if (-not (Test-Path -LiteralPath $Path)) {
+    return $null
+  }
+
+  Get-Content -LiteralPath $Path -Raw
+}
+
+function Test-ContainsAll {
+  param(
+    [string]$Content,
+    [string[]]$Terms
+  )
+
+  foreach ($term in $Terms) {
+    if ($Content -notmatch [regex]::Escape($term)) {
+      return $false
+    }
+  }
+
+  return $true
+}
+
+$issues = @()
+
+$contractsReadmePath = Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\contracts\README.md"
+$openapiPath = Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\contracts\openapi.yaml"
+$prismUsagePath = Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\contracts\prism-usage.md"
+$frontendArchitecturePath = Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\design\frontend-architecture.md"
+$apiMapPath = Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\context\API_MAP.md"
+
+$contractsReadme = Get-FileContentOrNull -Path $contractsReadmePath
+$openapi = Get-FileContentOrNull -Path $openapiPath
+$prismUsage = Get-FileContentOrNull -Path $prismUsagePath
+$frontendArchitecture = Get-FileContentOrNull -Path $frontendArchitecturePath
+$apiMap = Get-FileContentOrNull -Path $apiMapPath
+
+if ($null -eq $contractsReadme) {
+  $issues += New-Issue -Severity "error" -File "docs/codex-harness-engineering/templates/contracts/README.md" -Section "file" -Message "缺少 contract guide。"
+}
+else {
+  if (-not (Test-ContainsAll -Content $contractsReadme -Terms @("请求入口统一通过 generated client", "分页字段默认统一为 `page/pageSize`", "响应结构必须统一", "错误模型必须显式定义", "前端类型优先从 contract 生成"))) {
+    $issues += New-Issue -Severity "error" -File "docs/codex-harness-engineering/templates/contracts/README.md" -Section "contract-rules" -Message "contract guide 缺少第八章要求的统一请求入口、分页字段、响应包装、错误模型或类型生成规则。"
+  }
+}
+
+if ($null -eq $openapi) {
+  $issues += New-Issue -Severity "error" -File "docs/codex-harness-engineering/templates/contracts/openapi.yaml" -Section "file" -Message "缺少 OpenAPI 模板。"
+}
+else {
+  if (-not (Test-ContainsAll -Content $openapi -Terms @("name: page", "name: pageSize", "ErrorResponse", "code:", "message:"))) {
+    $issues += New-Issue -Severity "error" -File "docs/codex-harness-engineering/templates/contracts/openapi.yaml" -Section "api-shape" -Message "OpenAPI 模板缺少分页参数或统一错误结构样例。"
+  }
+}
+
+if ($null -eq $prismUsage) {
+  $issues += New-Issue -Severity "warning" -File "docs/codex-harness-engineering/templates/contracts/prism-usage.md" -Section "file" -Message "缺少 Prism 用法模板。"
+}
+else {
+  if (-not (Test-ContainsAll -Content $prismUsage -Terms @("request 参数名是否和 contract 一致", "response 包装层是否和 contract 一致", "错误响应是否都能命中", "generated client"))) {
+    $issues += New-Issue -Severity "warning" -File "docs/codex-harness-engineering/templates/contracts/prism-usage.md" -Section "validation-checks" -Message "Prism 用法模板还没有覆盖第八章的接口联调检查点。"
+  }
+}
+
+if ($null -eq $frontendArchitecture) {
+  $issues += New-Issue -Severity "error" -File "docs/codex-harness-engineering/templates/design/frontend-architecture.md" -Section "file" -Message "缺少 frontend-architecture 模板。"
+}
+else {
+  if (-not (Test-ContainsAll -Content $frontendArchitecture -Terms @("UI 字段必须能追溯到 contract", "页面或组件中不得直接手写 `fetch/axios/baseURL/token/error`", "前端不得再手写一套重复 request/response schema"))) {
+    $issues += New-Issue -Severity "error" -File "docs/codex-harness-engineering/templates/design/frontend-architecture.md" -Section "frontend-contract-boundary" -Message "frontend-architecture 模板缺少 contract 追溯或禁止手写请求逻辑的约束。"
+  }
+}
+
+if ($null -eq $apiMap) {
+  $issues += New-Issue -Severity "warning" -File "docs/codex-harness-engineering/templates/context/API_MAP.md" -Section "file" -Message "缺少 API_MAP 模板。"
+}
+else {
+  if (-not (Test-ContainsAll -Content $apiMap -Terms @("统一请求入口", "分页字段约定", "统一响应包装", "错误模型", "contract 位置"))) {
+    $issues += New-Issue -Severity "warning" -File "docs/codex-harness-engineering/templates/context/API_MAP.md" -Section "api-convention-fields" -Message "API_MAP 模板缺少统一请求入口、分页字段、响应包装或错误模型字段。"
+  }
+}
+
+$errors = @($issues | Where-Object { $_.severity -eq "error" })
+$warnings = @($issues | Where-Object { $_.severity -eq "warning" })
+$exitCode = if ($errors.Count -gt 0) { 1 } elseif ($warnings.Count -gt 0 -and -not $AllowWarningsOnly) { 2 } else { 0 }
+
+if ($AsJson) {
+  [PSCustomObject]@{
+    ok = ($exitCode -eq 0)
+    errors = $errors
+    warnings = $warnings
+  } | ConvertTo-Json -Depth 6
+  exit $exitCode
+}
+
+if ($errors.Count -eq 0 -and $warnings.Count -eq 0) {
+  Write-Output "Contract lint passed."
+  exit 0
+}
+
+if ($errors.Count -gt 0) {
+  Write-Output "Contract lint failed."
+  foreach ($issue in $errors) {
+    Write-Output ("- [ERROR] {0} :: {1} :: {2}" -f $issue.file, $issue.section, $issue.message)
+  }
+}
+
+if ($warnings.Count -gt 0) {
+  if ($errors.Count -eq 0) {
+    Write-Output "Contract lint passed with warnings."
+  }
+  foreach ($issue in $warnings) {
+    Write-Output ("- [WARNING] {0} :: {1} :: {2}" -f $issue.file, $issue.section, $issue.message)
+  }
+}
+
+exit $exitCode

package/package-source/docs/codex-harness-engineering/templates/tools/harness/data-lint.ps1

@@ -0,0 +1,37 @@
+param(
+  [string]$ProjectRoot = "",
+  [switch]$AsJson,
+  [switch]$AllowWarningsOnly
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+if ([string]::IsNullOrWhiteSpace($ProjectRoot)) {
+  $ProjectRoot = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot "..\..\..\.."))
+}
+
+function New-Issue { param([string]$Severity,[string]$File,[string]$Section,[string]$Message) [PSCustomObject]@{ severity=$Severity; file=$File; section=$Section; message=$Message } }
+function Get-FileContentOrNull { param([string]$Path) if (-not (Test-Path -LiteralPath $Path)) { return $null }; Get-Content -LiteralPath $Path -Raw }
+function Test-ContainsAll { param([string]$Content,[string[]]$Terms) foreach ($term in $Terms) { if ($Content -notmatch [regex]::Escape($term)) { return $false } }; return $true }
+
+$issues = @()
+$dataModel = Get-FileContentOrNull (Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\spec\10-data-model.md")
+$architecture = Get-FileContentOrNull (Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\docs\architecture-constraints.md")
+$currentTask = Get-FileContentOrNull (Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\context\CURRENT_TASK.md")
+
+if ($null -eq $dataModel) { $issues += New-Issue "error" "docs/codex-harness-engineering/templates/spec/10-data-model.md" "file" "缺少 10-data-model 模板。" }
+elseif (-not (Test-ContainsAll $dataModel @("schema_or_migration_required", "transaction_sensitive_writes", "migration_plan", "historical_data_compatibility", "rollback_strategy"))) { $issues += New-Issue "error" "docs/codex-harness-engineering/templates/spec/10-data-model.md" "migration-fields" "10-data-model 模板缺少第21章要求的 migration、历史数据和回滚字段。" }
+if ($null -eq $architecture) { $issues += New-Issue "error" "docs/codex-harness-engineering/templates/docs/architecture-constraints.md" "file" "缺少 architecture-constraints 模板。" }
+elseif (-not (Test-ContainsAll $architecture @("schema_or_migration_required", "historical_data_strategy", "migration_rollback_strategy", "consistency_requirements"))) { $issues += New-Issue "error" "docs/codex-harness-engineering/templates/docs/architecture-constraints.md" "data-boundary" "architecture-constraints 模板缺少第21章要求的数据迁移和历史数据约束。" }
+if ($null -eq $currentTask) { $issues += New-Issue "warning" "docs/codex-harness-engineering/templates/context/CURRENT_TASK.md" "file" "缺少 CURRENT_TASK 模板。" }
+elseif (-not (Test-ContainsAll $currentTask @("schema / migration 是否变更", "migration 文件 / 目录", "历史数据兼容 / 回填策略"))) { $issues += New-Issue "warning" "docs/codex-harness-engineering/templates/context/CURRENT_TASK.md" "data-change-fields" "CURRENT_TASK 模板缺少第21章要求的数据变更记录字段。" }
+
+$errors = @($issues | Where-Object severity -eq "error")
+$warnings = @($issues | Where-Object severity -eq "warning")
+$exitCode = if ($errors.Count -gt 0) { 1 } elseif ($warnings.Count -gt 0 -and -not $AllowWarningsOnly) { 2 } else { 0 }
+if ($AsJson) { [PSCustomObject]@{ ok = ($exitCode -eq 0); errors = $errors; warnings = $warnings } | ConvertTo-Json -Depth 6; exit $exitCode }
+if ($errors.Count -eq 0 -and $warnings.Count -eq 0) { Write-Output "Data lint passed."; exit 0 }
+if ($errors.Count -gt 0) { Write-Output "Data lint failed."; foreach ($issue in $errors) { Write-Output ("- [ERROR] {0} :: {1} :: {2}" -f $issue.file, $issue.section, $issue.message) } }
+if ($warnings.Count -gt 0) { if ($errors.Count -eq 0) { Write-Output "Data lint passed with warnings." }; foreach ($issue in $warnings) { Write-Output ("- [WARNING] {0} :: {1} :: {2}" -f $issue.file, $issue.section, $issue.message) } }
+exit $exitCode

package/package-source/docs/codex-harness-engineering/templates/tools/harness/directory-lint.ps1

@@ -0,0 +1,152 @@
+param(
+  [string]$ProjectRoot = "",
+  [switch]$AsJson,
+  [switch]$AllowWarningsOnly
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+if ([string]::IsNullOrWhiteSpace($ProjectRoot)) {
+  $ProjectRoot = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot "..\.."))
+}
+
+function New-Issue {
+  param(
+    [string]$Severity,
+    [string]$File,
+    [string]$Section,
+    [string]$Message
+  )
+
+  [PSCustomObject]@{
+    severity = $Severity
+    file = $File
+    section = $Section
+    message = $Message
+  }
+}
+
+function Get-FileContentOrNull {
+  param([string]$Path)
+
+  if (-not (Test-Path -LiteralPath $Path)) {
+    return $null
+  }
+
+  Get-Content -LiteralPath $Path -Raw
+}
+
+function Test-ContainsAll {
+  param(
+    [string]$Content,
+    [string[]]$Terms
+  )
+
+  foreach ($term in $Terms) {
+    if ($Content -notmatch [regex]::Escape($term)) {
+      return $false
+    }
+  }
+
+  return $true
+}
+
+function Test-ContainsAny {
+  param(
+    [string]$Content,
+    [string[]]$Terms
+  )
+
+  foreach ($term in $Terms) {
+    if ($Content -match [regex]::Escape($term)) {
+      return $true
+    }
+  }
+
+  return $false
+}
+
+$issues = @()
+
+$directoryTemplatePath = Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\docs\directory-structure-template.md"
+$repoMapPath = Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\context\repo-map.md"
+$currentTaskPath = Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\context\CURRENT_TASK.md"
+$projectAgentsTemplatePath = Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\docs\project-agents-template.md"
+
+$directoryTemplate = Get-FileContentOrNull -Path $directoryTemplatePath
+$repoMap = Get-FileContentOrNull -Path $repoMapPath
+$currentTask = Get-FileContentOrNull -Path $currentTaskPath
+$projectAgentsTemplate = Get-FileContentOrNull -Path $projectAgentsTemplatePath
+
+if ($null -eq $directoryTemplate) {
+  $issues += New-Issue -Severity "error" -File "docs/codex-harness-engineering/templates/docs/directory-structure-template.md" -Section "file" -Message "缺少目录结构模板，无法承载第四章目录规范。"
+}
+else {
+  if (-not (Test-ContainsAll -Content $directoryTemplate -Terms @("新文件放置规则", "禁止新增的目录名", "新增目录前必须回答", "业务域组织规则"))) {
+    $issues += New-Issue -Severity "error" -File "docs/codex-harness-engineering/templates/docs/directory-structure-template.md" -Section "directory-rules" -Message "目录结构模板缺少文件放置规则、禁止目录名、目录新增理由或业务域组织规则。"
+  }
+}
+
+if ($null -eq $repoMap) {
+  $issues += New-Issue -Severity "error" -File "docs/codex-harness-engineering/templates/context/repo-map.md" -Section "file" -Message "缺少 repo-map 模板，无法索引目录规则。"
+}
+else {
+  if (-not (Test-ContainsAll -Content $repoMap -Terms @("关键目录", "子目录规则索引"))) {
+    $issues += New-Issue -Severity "error" -File "docs/codex-harness-engineering/templates/context/repo-map.md" -Section "directory-index" -Message "repo-map 模板缺少关键目录或子目录规则索引。"
+  }
+}
+
+if ($null -eq $currentTask) {
+  $issues += New-Issue -Severity "error" -File "docs/codex-harness-engineering/templates/context/CURRENT_TASK.md" -Section "file" -Message "缺少 CURRENT_TASK 模板，无法记录目录新增理由。"
+}
+else {
+  if (-not (Test-ContainsAll -Content $currentTask -Terms @("这个功能属于哪个模块", "需要改哪些文件", "复用决定", "不复用理由"))) {
+    $issues += New-Issue -Severity "warning" -File "docs/codex-harness-engineering/templates/context/CURRENT_TASK.md" -Section "directory-decision-fields" -Message "CURRENT_TASK 模板缺少目录变更相关的模块归属或复用决策字段。"
+  }
+}
+
+if ($null -eq $projectAgentsTemplate) {
+  $issues += New-Issue -Severity "error" -File "docs/codex-harness-engineering/templates/docs/project-agents-template.md" -Section "file" -Message "缺少 project AGENTS 模板。"
+}
+else {
+  if (-not (Test-ContainsAny -Content $projectAgentsTemplate -Terms @("禁止新增 utils2、common2、helper2", "目录独有的模块职责", '子目录 `AGENTS.md`'))) {
+    $issues += New-Issue -Severity "warning" -File "docs/codex-harness-engineering/templates/docs/project-agents-template.md" -Section "directory-guidance" -Message "project AGENTS 模板对目录结构问题的约束仍不够直给。"
+  }
+}
+
+$errors = @($issues | Where-Object { $_.severity -eq "error" })
+$warnings = @($issues | Where-Object { $_.severity -eq "warning" })
+$exitCode = if ($errors.Count -gt 0) { 1 } elseif ($warnings.Count -gt 0 -and -not $AllowWarningsOnly) { 2 } else { 0 }
+
+if ($AsJson) {
+  [PSCustomObject]@{
+    ok = ($exitCode -eq 0)
+    errors = $errors
+    warnings = $warnings
+  } | ConvertTo-Json -Depth 6
+  exit $exitCode
+}
+
+if ($errors.Count -eq 0 -and $warnings.Count -eq 0) {
+  Write-Output "Directory lint passed."
+  exit 0
+}
+
+if ($errors.Count -gt 0) {
+  Write-Output "Directory lint failed."
+  foreach ($issue in $errors) {
+    Write-Output ("- [ERROR] {0} :: {1} :: {2}" -f $issue.file, $issue.section, $issue.message)
+  }
+}
+
+if ($warnings.Count -gt 0) {
+  if ($errors.Count -eq 0) {
+    Write-Output "Directory lint passed with warnings."
+  }
+  foreach ($issue in $warnings) {
+    Write-Output ("- [WARNING] {0} :: {1} :: {2}" -f $issue.file, $issue.section, $issue.message)
+  }
+}
+
+exit $exitCode

package/package-source/docs/codex-harness-engineering/templates/tools/harness/docs-lint.ps1

@@ -0,0 +1,40 @@
+param(
+  [string]$ProjectRoot = "",
+  [switch]$AsJson,
+  [switch]$AllowWarningsOnly
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+if ([string]::IsNullOrWhiteSpace($ProjectRoot)) {
+  $ProjectRoot = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot "..\..\..\.."))
+}
+
+function New-Issue { param([string]$Severity,[string]$File,[string]$Section,[string]$Message) [PSCustomObject]@{ severity=$Severity; file=$File; section=$Section; message=$Message } }
+function Get-FileContentOrNull { param([string]$Path) if (-not (Test-Path -LiteralPath $Path)) { return $null }; Get-Content -LiteralPath $Path -Raw }
+function Test-ContainsAll { param([string]$Content,[string[]]$Terms) foreach ($term in $Terms) { if ($Content -notmatch [regex]::Escape($term)) { return $false } }; return $true }
+
+$issues = @()
+$runtimeAgents = Get-FileContentOrNull (Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\runtime\AGENTS.md")
+$projectAgentsTemplate = Get-FileContentOrNull (Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\docs\project-agents-template.md")
+$newProjectUsage = Get-FileContentOrNull (Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\docs\new-project-usage.md")
+$currentTask = Get-FileContentOrNull (Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\context\CURRENT_TASK.md")
+
+if ($null -eq $runtimeAgents) { $issues += New-Issue "error" "docs/codex-harness-engineering/templates/runtime/AGENTS.md" "file" "缺少 runtime AGENTS 模板。" }
+elseif (-not (Test-ContainsAll $runtimeAgents @("docs/ai/repo-map.md", "docs/ai/CURRENT_TASK.md", "docs/harness/rule-governance.md"))) { $issues += New-Issue "error" "docs/codex-harness-engineering/templates/runtime/AGENTS.md" "doc-index" "runtime AGENTS 模板缺少第20章要求的核心文档入口索引。" }
+if ($null -eq $projectAgentsTemplate) { $issues += New-Issue "error" "docs/codex-harness-engineering/templates/docs/project-agents-template.md" "file" "缺少 project-agents-template 模板。" }
+elseif (-not (Test-ContainsAll $projectAgentsTemplate @("README.md", "docs/architecture.md", "docs/code-style.md", "docs/api-convention.md", "docs/component-map.md", "docs/test-strategy.md", "docs/current-task.md"))) { $issues += New-Issue "error" "docs/codex-harness-engineering/templates/docs/project-agents-template.md" "core-doc-set" "project AGENTS 模板缺少第20章要求的最小核心文档集。" }
+if ($null -eq $newProjectUsage) { $issues += New-Issue "warning" "docs/codex-harness-engineering/templates/docs/new-project-usage.md" "file" "缺少 new-project-usage 模板。" }
+elseif (-not (Test-ContainsAll $newProjectUsage @("repo-map.md", "CURRENT_TASK.md", "AGENTS.md", "README.md"))) { $issues += New-Issue "warning" "docs/codex-harness-engineering/templates/docs/new-project-usage.md" "bootstrap-doc-set" "new-project-usage 模板还没有把第20章要求的项目文档最小集合讲清。" }
+if ($null -eq $currentTask) { $issues += New-Issue "warning" "docs/codex-harness-engineering/templates/context/CURRENT_TASK.md" "file" "缺少 CURRENT_TASK 模板。" }
+elseif (-not (Test-ContainsAll $currentTask @("需要同步更新的文档", "交付验收报告路径"))) { $issues += New-Issue "warning" "docs/codex-harness-engineering/templates/context/CURRENT_TASK.md" "doc-update-fields" "CURRENT_TASK 模板缺少文档更新和交付报告字段。" }
+
+$errors = @($issues | Where-Object severity -eq "error")
+$warnings = @($issues | Where-Object severity -eq "warning")
+$exitCode = if ($errors.Count -gt 0) { 1 } elseif ($warnings.Count -gt 0 -and -not $AllowWarningsOnly) { 2 } else { 0 }
+if ($AsJson) { [PSCustomObject]@{ ok = ($exitCode -eq 0); errors = $errors; warnings = $warnings } | ConvertTo-Json -Depth 6; exit $exitCode }
+if ($errors.Count -eq 0 -and $warnings.Count -eq 0) { Write-Output "Docs lint passed."; exit 0 }
+if ($errors.Count -gt 0) { Write-Output "Docs lint failed."; foreach ($issue in $errors) { Write-Output ("- [ERROR] {0} :: {1} :: {2}" -f $issue.file, $issue.section, $issue.message) } }
+if ($warnings.Count -gt 0) { if ($errors.Count -eq 0) { Write-Output "Docs lint passed with warnings." }; foreach ($issue in $warnings) { Write-Output ("- [WARNING] {0} :: {1} :: {2}" -f $issue.file, $issue.section, $issue.message) } }
+exit $exitCode