@pzy560117/codex-harness 0.1.7 → 0.1.8

package/README.md

@@ -106,7 +106,7 @@ harness init --plan
 ### 钉住远程版本初始化
 
 ```powershell
-npx @pzy560117/codex-harness init --version 0.1.7
+npx @pzy560117/codex-harness init --version 0.1.8
 ```
 
 适合 release smoke 或回滚到某个已发布版本。

package/package-source/AGENTS.md

@@ -7,6 +7,13 @@
 - 当前仓库根目录下的活跃文档或脚本，只在它本身就是 canonical，或为了验证模板落地效果、保持当前仓库可运行时再同步修改。
 - 如果一次改动同时涉及根目录活跃文件和模板文件，优先说明哪一份是 canonical，避免只修当前仓库、不修模板源。
 
+## 任务结构硬门禁
+
+- 未经用户明确同意，不得把标准 `task.json` 模板 phase 压缩成更少任务；正式任务队列至少保留 `ANALYSIS-001`、`TESTCASE-001`、`PLAN-001`。
+- P0/P1 项目禁止跳过 `TESTCASE-001`；缺少 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md`、`ACCEPTANCE_CRITERIA.md`、`TRACEABILITY_MATRIX.md`、`TEST_DATA_MATRIX.md`、`REGRESSION_PLAN.md`、`verify-matrix.md` 任一项，都不得生成最终 `task.json`。
+- `feature_impl` 没有 `qa_contract` 不得进入正式任务队列；`qa_contract` 没有完整 `tdd_contract`、`development_validation`、`acceptance_validation` 不得开始实现。
+- 单个 `feature_impl` 默认不得覆盖超过 3 条主需求；订单、支付、库存、RBAC 必须拆独立任务；前端和后端不得长期混在同一个 story，除非这是明确的 `release` 任务。
+
 ## 目录级规则
 
 - 当某个目录满足以下任一条件时，应优先考虑新增或更新该目录下的 `AGENTS.md`，而不是继续扩充根入口：

package/package-source/docs/codex-harness-engineering/templates/bootstrap-codex-harness.ps1

@@ -57,7 +57,7 @@ function Resolve-TemplateRoot {
     }
 
     $agentsTemplate = Join-Path $resolved "runtime\AGENTS.md"
-    $driverTemplate = Join-Path $resolved "runtime\codex-loop.ps1"
+    $driverTemplate = Join-Path $resolved "runtime\codex-loop.ps1"
     if ((Test-Path -LiteralPath $agentsTemplate) -and (Test-Path -LiteralPath $driverTemplate)) {
       return $resolved
     }
@@ -225,16 +225,28 @@ function Ensure-TaskFile {
     return Copy-ManagedFile -SourceRoot $SourceRoot -SourceRelativePath "runtime\task.json" -DestinationRoot $DestinationRoot -DestinationRelativePath "task.json" -Overwrite:$true
   }
 
-  $taskDocument = $taskContent | ConvertFrom-Json
-  if ($null -eq $taskDocument.runtime) {
-    $taskDocument | Add-Member -NotePropertyName "runtime" -NotePropertyValue ([PSCustomObject]@{}) -Force
-  }
-
-  if ([string]::IsNullOrWhiteSpace($taskDocument.runtime.driver)) {
-    $taskDocument.runtime.driver = "powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/codex-loop.ps1"
-    $taskDocument | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $taskPath -Encoding UTF8
-    return [PSCustomObject]@{
-      Path = $taskPath
+  $taskDocument = $taskContent | ConvertFrom-Json
+  if ($null -eq $taskDocument.runtime) {
+    $taskDocument | Add-Member -NotePropertyName "runtime" -NotePropertyValue ([PSCustomObject]@{}) -Force
+  }
+
+  $canonicalDriver = "powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\codex-loop.ps1"
+  $driverPattern = 'tools[\\/]+harness[\\/]+tools[\\/]+harness[\\/]+codex-loop\.ps1'
+
+  if ([string]::IsNullOrWhiteSpace($taskDocument.runtime.driver)) {
+    $taskDocument.runtime.driver = $canonicalDriver
+    $taskDocument | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $taskPath -Encoding UTF8
+    return [PSCustomObject]@{
+      Path = $taskPath
+      Action = "updated"
+    }
+  }
+
+  if ([string]$taskDocument.runtime.driver -match $driverPattern) {
+    $taskDocument.runtime.driver = $canonicalDriver
+    $taskDocument | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $taskPath -Encoding UTF8
+    return [PSCustomObject]@{
+      Path = $taskPath
       Action = "updated"
     }
   }
@@ -293,11 +305,25 @@ function Resolve-LockManifestSourcePath {
   return Join-Path $PackageRoot ($normalizedSource.Replace('/', '\'))
 }
 
-function Get-FileSha256 {
-  param([string]$Path)
-
-  return (Get-FileHash -LiteralPath $Path -Algorithm SHA256).Hash.ToLowerInvariant()
-}
+function Get-FileSha256 {
+  param([string]$Path)
+
+  $hashAlgorithm = [System.Security.Cryptography.SHA256]::Create()
+  try {
+    $stream = [System.IO.File]::OpenRead($Path)
+    try {
+      $hashBytes = $hashAlgorithm.ComputeHash($stream)
+    }
+    finally {
+      $stream.Dispose()
+    }
+  }
+  finally {
+    $hashAlgorithm.Dispose()
+  }
+
+  return ([System.BitConverter]::ToString($hashBytes)).Replace('-', '').ToLowerInvariant()
+}
 
 function Add-LockManagedFile {
   param(
@@ -561,13 +587,14 @@ $results = @()
 
 $rootFiles = @(
   @{ Source = "runtime\AGENTS.md"; Destination = "AGENTS.md" },
-  @{ Source = "tools/install/bootstrap-codex-harness.ps1"; Destination = "tools\\install/bootstrap-codex-harness.ps1" },
-  @{ Source = "runtime\codex-loop.ps1"; Destination = "tools\\harness/codex-loop.ps1" },
-  @{ Source = "runtime\doctor.ps1"; Destination = "tools\\harness/doctor.ps1" },
+  @{ Source = "bootstrap-codex-harness.ps1"; Destination = "tools\install\bootstrap-codex-harness.ps1" },
+  @{ Source = "runtime\codex-loop.ps1"; Destination = "tools\harness\codex-loop.ps1" },
+  @{ Source = "runtime\doctor.ps1"; Destination = "tools\harness\doctor.ps1" },
   @{ Source = "config\codex-config.toml"; Destination = ".codex\config.toml" },
   @{ Source = "config\codex-readme.md"; Destination = ".codex\README.md" },
-  @{ Source = "hooks\hooks.json"; Destination = ".codex\hooks.json" },
+  @{ Source = "hooks\hooks.json"; Destination = ".codex\hooks.json" },
   @{ Source = "hooks\hook-stop-verify.ps1"; Destination = "tools\harness\hook-stop-verify.ps1" },
+  @{ Source = "scripts\harness\harness-governance-check.ps1"; Destination = "scripts\harness\harness-governance-check.ps1" },
   @{ Source = "scripts\ai-workflow\check-ai-sync-drift.ps1"; Destination = "tools\install\ai-workflow\check-ai-sync-drift.ps1" },
   @{ Source = "runtime\task-run-profile.json"; Destination = ".codex\task-run-profile.json" },
   @{ Source = "prompts\implement-one-task.md"; Destination = ".codex\prompts\implement-one-task.md" },
@@ -586,33 +613,16 @@ $rootFiles = @(
   @{ Source = "prompts\worker-role\harness-writer.md"; Destination = ".codex\prompts\worker-role\harness-writer.md" },
   @{ Source = "runtime\smoke-task.json"; Destination = "tools\harness\templates\smoke-task.json" },
   @{ Source = "runtime\project-task-template.json"; Destination = "tools\harness\templates\project-task-template.json" },
-  @{ Source = "runtime\verify.ps1"; Destination = "tools\\harness/verify.ps1" },
-  @{ Source = "tools\harness\spec-lint.ps1"; Destination = "tools\\harness/spec-lint.ps1" },
-  @{ Source = "tools\harness\docs-lint.ps1"; Destination = "tools\\harness/docs-lint.ps1" },
-  @{ Source = "tools\harness\data-lint.ps1"; Destination = "tools\\harness/data-lint.ps1" },
-  @{ Source = "tools\harness\integration-lint.ps1"; Destination = "tools\\harness/integration-lint.ps1" },
-  @{ Source = "tools\harness\mobile-lint.ps1"; Destination = "tools\\harness/mobile-lint.ps1" },
-  @{ Source = "tools\harness\acceptance-lint.ps1"; Destination = "tools\\harness/acceptance-lint.ps1" },
-  @{ Source = "tools\harness\context-lint.ps1"; Destination = "tools\\harness/context-lint.ps1" },
-  @{ Source = "tools\harness\architecture-lint.ps1"; Destination = "tools\\harness/architecture-lint.ps1" },
-  @{ Source = "tools\harness\directory-lint.ps1"; Destination = "tools\\harness/directory-lint.ps1" },
-  @{ Source = "tools\harness\component-lint.ps1"; Destination = "tools\\harness/component-lint.ps1" },
-  @{ Source = "tools\harness\business-lint.ps1"; Destination = "tools\\harness/business-lint.ps1" },
-  @{ Source = "tools\harness\contract-lint.ps1"; Destination = "tools\\harness/contract-lint.ps1" },
-  @{ Source = "tools\harness\state-lint.ps1"; Destination = "tools\\harness/state-lint.ps1" },
-  @{ Source = "tools\harness\ui-lint.ps1"; Destination = "tools\\harness/ui-lint.ps1" },
-  @{ Source = "tools\harness\backend-lint.ps1"; Destination = "tools\\harness/backend-lint.ps1" },
-  @{ Source = "tools\harness\security-lint.ps1"; Destination = "tools\\harness/security-lint.ps1" },
-  @{ Source = "tools\harness\testing-lint.ps1"; Destination = "tools\\harness/testing-lint.ps1" },
-  @{ Source = "tools\harness\impact-lint.ps1"; Destination = "tools\\harness/impact-lint.ps1" },
-  @{ Source = "tools\harness\performance-lint.ps1"; Destination = "tools\\harness/performance-lint.ps1" },
-  @{ Source = "tools\harness\config-lint.ps1"; Destination = "tools\\harness/config-lint.ps1" },
-  @{ Source = "tools\harness\observability-lint.ps1"; Destination = "tools\\harness/observability-lint.ps1" },
-  @{ Source = "tools\harness\refactor-lint.ps1"; Destination = "tools\\harness/refactor-lint.ps1" },
-  @{ Source = "tools\harness\session-lint.ps1"; Destination = "tools\\harness/session-lint.ps1" },
-  @{ Source = "tools\harness\style-lint.ps1"; Destination = "tools\\harness/style-lint.ps1" },
-  @{ Source = "config\tools/install/env-check.ps1"; Destination = "tools\\install/env-check.ps1" },
-  @{ Source = "trace\docs/harness/trace.schema.json"; Destination = "docs\\harness/trace.schema.json" }
+  @{ Source = "tools\harness\task-structure-lint.ps1"; Destination = "tools\harness\task-structure-lint.ps1" },
+  @{ Source = "runtime\verify.ps1"; Destination = "tools\harness\verify.ps1" },
+  @{ Source = "tools\harness\docs-lint.ps1"; Destination = "tools\harness\docs-lint.ps1" },
+  @{ Source = "tools\harness\data-lint.ps1"; Destination = "tools\harness\data-lint.ps1" },
+  @{ Source = "tools\harness\integration-lint.ps1"; Destination = "tools\harness\integration-lint.ps1" },
+  @{ Source = "tools\harness\mobile-lint.ps1"; Destination = "tools\harness\mobile-lint.ps1" },
+  @{ Source = "tools\harness\acceptance-lint.ps1"; Destination = "tools\harness\acceptance-lint.ps1" },
+  @{ Source = "tools\harness\session-lint.ps1"; Destination = "tools\harness\session-lint.ps1" },
+  @{ Source = "config\env-check.ps1"; Destination = "tools\install\env-check.ps1" },
+  @{ Source = "trace\trace.schema.json"; Destination = "docs\harness\trace.schema.json" }
 )
 
 foreach ($file in $rootFiles) {
@@ -735,7 +745,6 @@ if ($Profile -eq "legacy" -and $IncludeDocs) {
     @{ Source = "docs\prompt-knowledge-integration.md"; Destination = "docs/harness/prompt-knowledge-integration.md" },
     @{ Source = "docs\mcp-knowledge-governance.md"; Destination = "docs/harness/mcp-knowledge-governance.md" },
     @{ Source = "docs\code-semantics-and-navigation.md"; Destination = "docs/harness/code-semantics-and-navigation.md" },
-    @{ Source = "docs\code-style-and-naming.md"; Destination = "docs/harness/code-style-and-naming.md" },
     @{ Source = "docs\rule-governance.md"; Destination = "docs/harness/rule-governance.md" },
     @{ Source = "docs\regression-rules.md"; Destination = "docs/harness/regression-rules.md" },
     @{ Source = "docs\team-knowledge-sync.md"; Destination = "docs/harness/team-knowledge-sync.md" },

package/package-source/docs/codex-harness-engineering/templates/docs/task-session-strategy.md

@@ -26,12 +26,16 @@
 - 标准交接入口是 `tools/harness/templates/project-task-template.json`，首个任务固定为 `INIT-001`，用于锁定 spec 输入、任务依赖、验证矩阵、`execution.mode` 和 owned paths。
 - 如果 `task.json` 为空文件，先初始化为合法 JSON；如果仍是 smoke 模板或示例任务，先替换为当前项目真实任务。
 - 交互开发模式可以决定新增或更新哪些待办任务，但实际写入必须委派给 `harness-writer` 等匹配 writer。
+- 未经用户明确同意，不得把标准模板 phase 压缩成更少任务；正式任务队列至少保留 `ANALYSIS-001`、`TESTCASE-001`、`PLAN-001`。
 - 任务进入 driver 前必须冻结交付语义：`scope`、`non_goals`、`entrypoints`、`inputs_outputs`、`failure_policy`、`rollback_strategy`、`state_surface`、`writeback_targets`。不适用字段必须写 `not_applicable`，不能留给实现会话猜。
 - 进入实现前，`docs/ai/CURRENT_TASK.md` 必须能回答本轮已完成内容、剩余问题、修改文件、测试结果、风险点和下一步，不允许只靠聊天记忆续跑。
+- `ANALYSIS-001`、`TESTCASE-001`、`PLAN-001` 的 testing truth source 产物必须在生成最终 `task.json` 前补齐：`docs/testing/ACCEPTANCE_CRITERIA.md`、`docs/testing/NATURAL_LANGUAGE_TEST_CASES.md`、`docs/testing/TRACEABILITY_MATRIX.md`、`docs/testing/TEST_DATA_MATRIX.md`、`docs/testing/REGRESSION_PLAN.md`、`docs/testing/verify-matrix.md`。缺任一项都不得进入正式任务队列。
 - 创建或重建任务队列时必须一次性补齐每个任务的完整交接字段：`requirement_ids`、`owned_paths`、`context_files`、`produces_artifacts`、`test_command`、`acceptance`、自然语言测试用例、测试数据、开发验证、最终验收验证、证据路径和 `qa_contract`。不得创建“先跑起来、后面再补测试/证据/整链路”的实现任务。
 - PRD / 需求文档完成后、进入实现前必须有自然语言测试用例阶段；每条 P0/P1 需求必须按 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md` 的需求类型覆盖矩阵满足最小用例数，并回溯到 Requirement ID、PRD 来源、Oracle、测试数据、证据路径和 TDD RED 预期失败。
 - 每个 `feature_impl` 任务必须声明两段验证：`development_validation` 用于编码过程中的 affected tests、单元 / 组件、局部 API、契约、类型检查或 lint；`acceptance_validation` 用于代码写完后从用户故事入口重新跑完整链路。
 - 每个 `feature_impl.qa_contract.tdd_contract.red.source_case_ids` 必须能回溯到 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md`；缺少自然语言用例来源时不得进入实现阶段。
+- 每个 `feature_impl.qa_contract.required_layers` 必须至少包含 `unit_or_component`、`contract_or_api`、`story_full_chain`、`affected_regression`；`tdd_contract` 必须同时包含 `red`、`green`、`refactor_guard`，且 `source_case_ids` 不得为空。
+- 单个 `feature_impl` 默认不得覆盖超过 3 条主需求；订单、支付、库存、RBAC 必须拆成独立任务；前端和后端不得长期混在同一个 story，除非这是明确的 `release` 任务。只有用户明确批准时，才允许在任务中增加 `decomposition_exemption` 记录例外原因。
 - 不适合作为 TDD RED 的自然语言用例必须通过 `story_full_chain.source_case_ids`、`acceptance_validation.source_case_ids`、回归计划或 `verify-matrix` 进入验收链路；不得只保留在 PRD 或测试设计文档中。
 - 每个 `feature_impl` 的验收链路必须包含入口、动作、Oracle、副作用/无副作用证据、测试数据、失败态证据和 release 影响。单元测试、小范围 smoke、静态检查或 `git diff --check` 只能作为开发验证的一层，不能替代最终验收链路。
 - 后端、CLI、worker、数据同步和外部集成类 `feature_impl` 必须按 `static`、`unit`、`chain`、`failure`、`writeback` 五层声明验证；没有 UI 可见结果时，链路验证和失败验证不能省略。

package/package-source/docs/codex-harness-engineering/templates/hooks/hook-stop-verify.ps1

@@ -608,6 +608,57 @@ function Invoke-HarnessGovernanceCheck {
   }
 }
 
+function Invoke-TaskStructureValidation {
+  param([string]$Root)
+
+  $scriptPath = Join-Path $Root "tools\harness\task-structure-lint.ps1"
+  if (-not (Test-Path -LiteralPath $scriptPath -PathType Leaf)) {
+    return [pscustomobject]@{
+      status = "fail"
+      findings = @([pscustomobject]@{
+          severity = "error"
+          code = "missing_task_structure_lint"
+          message = "缺少 task structure lint: tools\\harness\\task-structure-lint.ps1"
+          task_id = ""
+          field = "tools/harness/task-structure-lint.ps1"
+        })
+    }
+  }
+
+  try {
+    return (& powershell -NoProfile -ExecutionPolicy Bypass -File $scriptPath -ProjectRoot $Root -JsonOutput | ConvertFrom-Json)
+  }
+  catch {
+    return [pscustomobject]@{
+      status = "fail"
+      findings = @([pscustomobject]@{
+          severity = "error"
+          code = "task_structure_lint_failed"
+          message = "task structure lint 执行失败: $($_.Exception.Message)"
+          task_id = ""
+          field = "task.json"
+        })
+    }
+  }
+}
+
+function ConvertTo-TaskStructureFindingText {
+  param([object]$ValidationResult)
+
+  $lines = @()
+  foreach ($finding in @($ValidationResult.findings)) {
+    $taskLabel = if ([string]::IsNullOrWhiteSpace([string]$finding.task_id)) { "" } else { " task=$($finding.task_id)" }
+    $fieldLabel = if ([string]::IsNullOrWhiteSpace([string]$finding.field)) { "" } else { " field=$($finding.field)" }
+    $lines += "- [$($finding.severity)] $($finding.code)$taskLabel${fieldLabel}: $($finding.message)"
+  }
+
+  if ($lines.Count -eq 0) {
+    return "- (none)"
+  }
+
+  return ($lines -join "`n")
+}
+
 function Block-WithState {
   param(
     [string]$Root,
@@ -759,16 +810,31 @@ Initialize task.json with a valid harness task queue, then rerun the driver or v
 "@
   }
 
-  if ($tasks.Count -eq 0) {
-    Block-WithState -Root $resolvedProjectRoot -EvidenceKey $evidenceKey -ReasonCode "task_queue_empty" -Reason @"
-Harness stop gate: task.json contains no tasks.
-
-Next action:
-Initialize a real harness task queue before ending the session.
-"@
-  }
-
-  $pendingCount = Get-PendingTaskCount -Tasks $tasks
+  if ($tasks.Count -eq 0) {
+    Block-WithState -Root $resolvedProjectRoot -EvidenceKey $evidenceKey -ReasonCode "task_queue_empty" -Reason @"
+Harness stop gate: task.json contains no tasks.
+
+Next action:
+Initialize a real harness task queue before ending the session.
+"@
+  }
+
+  $taskStructureResult = Invoke-TaskStructureValidation -Root $resolvedProjectRoot
+  if ([string]$taskStructureResult.status -eq "fail") {
+    $findingText = ConvertTo-TaskStructureFindingText -ValidationResult $taskStructureResult
+    Block-WithState -Root $resolvedProjectRoot -EvidenceKey $evidenceKey -ReasonCode "task_structure_invalid" -Reason @"
+Harness stop gate: task.json 未通过结构门禁。
+
+Findings:
+$findingText
+
+Next action:
+补齐缺失 phase、testing truth source、qa_contract、tdd_contract 或拆分过大的 feature_impl 后，再运行:
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\verify.ps1
+"@
+  }
+
+  $pendingCount = Get-PendingTaskCount -Tasks $tasks
   if ($pendingCount -le 0) {
     Block-OnTraceEvidenceIfNeeded -Root $resolvedProjectRoot -EvidenceKey $evidenceKey -TraceInfo $latestTraceInfo
     Exit-Allow

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/examples/ticket-filter-demo/task.json

@@ -1,6 +1,6 @@
 {
   "runtime": {
-    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/codex-loop.ps1",
+    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\codex-loop.ps1",
     "run_profile": ".codex\\task-run-profile.json"
   },
   "tasks": [
@@ -43,7 +43,7 @@
         "如有需要补齐 demo 资产",
         "运行 tools/harness/verify.ps1 验证 demo 闭环"
       ],
-      "test_command": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/verify.ps1",
+      "test_command": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\verify.ps1",
       "acceptance": [
         "demo 目录同时具备 product、design、frontend architecture、dev-plan、contract、component、story、generated client",
         "tools/harness/verify.ps1 通过",

package/package-source/docs/codex-harness-engineering/templates/runtime/AGENTS.md

@@ -30,6 +30,10 @@
 - 不要删除或改写已有任务描述，除非用户明确要求替换模板示例或重建任务队列。
 - 修改后必须运行与改动直接对应的验证；文档改动至少运行 `git diff --check`。
 - 测试范围从需求收敛阶段开始定义；P0/P1 需求进入实现前必须有可追溯验收、测试数据和证据路径。
+- 未经用户明确同意，不得把标准模板 phase 压缩成更少任务；正式任务队列至少保留 `ANALYSIS-001`、`TESTCASE-001`、`PLAN-001` 三段测试左移与实施计划 phase。
+- P0/P1 任务禁止跳过 `TESTCASE-001`；没有自然语言测试用例、测试数据矩阵、回归计划和验证矩阵，不得生成最终 `task.json`。
+- `feature_impl` 没有 `qa_contract` 不得进入正式 `task.json`；`qa_contract` 没有完整 `tdd_contract`、开发验证和最终验收验证，不得开始实现。
+- 单个 `feature_impl` 默认不得覆盖超过 3 条主需求；订单、支付、库存、RBAC 必须拆成独立任务；前端和后端不得长期混在同一个 story，除非这是明确的 `release` 任务。
 - 外部系统、开源栈、第三方平台或真实环境集成需求，完成声明必须包含真实依赖接入、成功态证据和失败态证据。
 - 进入实现前必须有当前项目声明的架构约束 truth source，默认路径为 `docs/architecture/constraints.md`，也可由 `task.json.runtime.handoff.truth_sources.architecture` 指向其他路径。
 - `feature_impl` 任务必须携带可执行的 `architecture_constraints`、`forbidden_implementations` 和对应验证命令；禁止用测试替身、local-only adapter 或领域原型冒充任务声明的交付路径。

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

@@ -57,14 +57,50 @@ function Add-DoctorError {
   $Errors.Value += $Message
 }
 
-function Add-DoctorWarning {
-  param(
-    [ref]$Warnings,
-    [string]$Message
-  )
-
-  $Warnings.Value += $Message
-}
+function Add-DoctorWarning {
+  param(
+    [ref]$Warnings,
+    [string]$Message
+  )
+
+  $Warnings.Value += $Message
+}
+
+function Invoke-TaskStructureValidation {
+  param(
+    [string]$Root,
+    [ref]$Errors,
+    [ref]$Warnings
+  )
+
+  $scriptPath = Join-Path $Root "tools\harness\task-structure-lint.ps1"
+  if (-not (Test-Path -LiteralPath $scriptPath -PathType Leaf)) {
+    Add-DoctorError -Errors $Errors -Message "缺少 task structure lint: tools\\harness\\task-structure-lint.ps1"
+    return
+  }
+
+  try {
+    $result = & powershell -NoProfile -ExecutionPolicy Bypass -File $scriptPath -ProjectRoot $Root -JsonOutput | ConvertFrom-Json
+  }
+  catch {
+    Add-DoctorError -Errors $Errors -Message "task structure lint 执行失败: $($_.Exception.Message)"
+    return
+  }
+
+  foreach ($finding in @($result.findings)) {
+    $message = [string]$finding.message
+    if (-not [string]::IsNullOrWhiteSpace([string]$finding.task_id)) {
+      $message = "task $($finding.task_id): $message"
+    }
+
+    if ($finding.severity -eq "warning") {
+      Add-DoctorWarning -Warnings $Warnings -Message $message
+    }
+    else {
+      Add-DoctorError -Errors $Errors -Message $message
+    }
+  }
+}
 
 function Get-DoctorFileSha256 {
   param([string]$Path)
@@ -1017,15 +1053,16 @@ $isThinProjectInstall = $harnessConfigInfo.Exists -and $harnessConfigInfo.Valid
 $isVendorProjectInstall = $harnessConfigInfo.Exists -and $harnessConfigInfo.Valid -and $harnessConfigInfo.InstallScope -eq "vendor"
 $isNotInstalledProject = $baseProjectShape -eq "not-installed"
 
-$requiredRootFiles = @(
-  "AGENTS.md",
+$requiredRootFiles = @(
+  "AGENTS.md",
   "tools\harness\codex-loop.ps1",
   "tools\harness\doctor.ps1",
+  "tools\harness\task-structure-lint.ps1",
   "tools\harness\verify.ps1",
   "tools\install\env-check.ps1",
   "task.json",
   "docs\harness\trace.schema.json"
-)
+)
 
 $requiredPromptFiles = @(
   ".codex\\prompts\\implement-one-task.md",
@@ -1143,11 +1180,37 @@ elseif (-not $isVendorProjectInstall) {
     Add-DoctorError -Errors ([ref]$errors) -Message "task.json 仍包含模板占位符，请先替换为当前项目真实任务。"
   }
 
-  $taskDocument = $taskContent | ConvertFrom-Json
-  $runtime = $taskDocument.runtime
-  $runProfileRelativePath = $DefaultRunProfile
-  if ($null -ne $runtime -and -not [string]::IsNullOrWhiteSpace($runtime.run_profile)) {
-    $runProfileRelativePath = $runtime.run_profile
+  $taskDocument = $taskContent | ConvertFrom-Json
+  $runtime = $taskDocument.runtime
+  if ($null -eq $runtime -or [string]::IsNullOrWhiteSpace([string]$runtime.driver)) {
+    Add-DoctorError -Errors ([ref]$errors) -Message "task.json 缺少 runtime.driver"
+  }
+  else {
+    $driverCommand = [string]$runtime.driver
+    if ($driverCommand -match 'tools[\\/]+harness[\\/]+tools[\\/]+harness[\\/]+codex-loop\.ps1') {
+      Add-DoctorError -Errors ([ref]$errors) -Message "task.json 的 runtime.driver 包含重复路径段 tools/harness/tools/harness，请改为 .\\tools\\harness\\codex-loop.ps1"
+    }
+
+    $driverFileMatch = [regex]::Match($driverCommand, '(?i)-File\s+("?)([^"]+)\1')
+    if (-not $driverFileMatch.Success) {
+      Add-DoctorError -Errors ([ref]$errors) -Message "task.json 的 runtime.driver 不是可解析的 PowerShell -File 命令: $driverCommand"
+    }
+    else {
+      $driverRelativePath = $driverFileMatch.Groups[2].Value.Replace('/', '\')
+      if ($driverRelativePath.StartsWith('.\')) {
+        $driverRelativePath = $driverRelativePath.Substring(2)
+      }
+
+      $driverPath = Join-Path $resolvedProjectRoot $driverRelativePath
+      if (-not (Test-Path -LiteralPath $driverPath)) {
+        Add-DoctorError -Errors ([ref]$errors) -Message "task.json 的 runtime.driver 指向不存在的脚本: $driverRelativePath"
+      }
+    }
+  }
+
+  $runProfileRelativePath = $DefaultRunProfile
+  if ($null -ne $runtime -and -not [string]::IsNullOrWhiteSpace($runtime.run_profile)) {
+    $runProfileRelativePath = $runtime.run_profile
   }
 
   $runProfilePath = Join-Path $resolvedProjectRoot $runProfileRelativePath
@@ -1204,7 +1267,7 @@ elseif (-not $isVendorProjectInstall) {
   }
 
   $taskIds = @{}
-  foreach ($task in @($taskDocument.tasks)) {
+  foreach ($task in @($taskDocument.tasks)) {
     if ($null -eq $task.id -or [string]::IsNullOrWhiteSpace([string]$task.id)) {
       Add-DoctorError -Errors ([ref]$errors) -Message "存在缺少 id 的任务。"
       continue
@@ -1231,13 +1294,15 @@ elseif (-not $isVendorProjectInstall) {
 
     $requiredTruthSourcesProperty = $task.PSObject.Properties["required_truth_sources"]
     $requiredTruthSources = if ($null -ne $requiredTruthSourcesProperty) { $requiredTruthSourcesProperty.Value } else { @() }
-    foreach ($truthSource in @($requiredTruthSources)) {
-      if ($allowedTruthSources -notcontains [string]$truthSource) {
-        Add-DoctorError -Errors ([ref]$errors) -Message "任务 $($task.id) 使用了未知 required_truth_source: $truthSource"
-      }
-    }
-  }
-}
+    foreach ($truthSource in @($requiredTruthSources)) {
+      if ($allowedTruthSources -notcontains [string]$truthSource) {
+        Add-DoctorError -Errors ([ref]$errors) -Message "任务 $($task.id) 使用了未知 required_truth_source: $truthSource"
+      }
+    }
+  }
+
+  Invoke-TaskStructureValidation -Root $resolvedProjectRoot -Errors ([ref]$errors) -Warnings ([ref]$warnings)
+}
 
 Write-DoctorReadiness `
   -Root $resolvedProjectRoot `

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

@@ -1,6 +1,6 @@
 {
   "runtime": {
-    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/codex-loop.ps1",
+    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\codex-loop.ps1",
     "trace_dir": "traces",
     "agent": "codex",
     "run_profile": ".codex\\task-run-profile.json",
@@ -92,12 +92,13 @@
       "execution": {
         "mode": "single"
       },
-      "steps": [
-        "把模板中的 <feature-slug>、用户故事标题、requirement_ids、owned_paths、context_files 和 test_command 全部替换成当前项目真实值",
-        "确认 task 依赖、优先级、execution.mode 和 non_blocking_dirty_paths 已与当前项目约束一致",
-        "确认架构约束 truth source 已明确交付形态、公开入口、数据边界、异步边界、测试替身策略、禁止实现和 Definition of Done；如项目不用默认路径，更新 runtime.handoff.truth_sources.architecture",
-        "确认当前 task.json 已经是正式任务队列，不再保留领域示例、smoke 占位或过期路径"
-      ],
+      "steps": [
+        "把模板中的 <feature-slug>、用户故事标题、requirement_ids、owned_paths、context_files 和 test_command 全部替换成当前项目真实值",
+        "确认 task 依赖、优先级、execution.mode 和 non_blocking_dirty_paths 已与当前项目约束一致",
+        "不得删除 ANALYSIS-001、TESTCASE-001、PLAN-001；未经用户明确批准并记录例外原因，不得压缩标准模板 phase",
+        "确认架构约束 truth source 已明确交付形态、公开入口、数据边界、异步边界、测试替身策略、禁止实现和 Definition of Done；如项目不用默认路径，更新 runtime.handoff.truth_sources.architecture",
+        "确认当前 task.json 已经是正式任务队列，不再保留领域示例、smoke 占位或过期路径"
+      ],
       "test_command": "git diff --check",
       "acceptance": [
         "任务队列只保留当前项目真实阶段与用户故事",
@@ -354,7 +355,9 @@
         "把后续实现按用户故事顺序映射到 dev-plan、affected tests、验证命令和证据路径",
         "把自然语言测试用例中的 TDD 候选转换为每个 feature_impl.qa_contract.tdd_contract，并保留 source_case_ids",
         "把非 TDD 自然语言用例映射到 feature_impl.qa_contract.story_full_chain.source_case_ids、acceptance_validation.source_case_ids、回归计划或 verify-matrix",
+        "不要把模板 phase 合并成更少任务；如果用户明确批准压缩，必须在对应任务补充 decomposition_exemption 记录批准范围和原因",
         "确认每个实现任务都已有 requirement_ids、owned_paths、context_files 和最小可行验收闭环",
+        "确认每个 feature_impl 默认不超过 3 条主 requirement_ids；订单、支付、库存、RBAC 拆成独立任务；前端和后端不要长期混在同一个 story",
         "对涉及用户可见行为、路由、表单、权限、状态流转或关键业务闭环的任务，明确是否要求 docs/testing/e2e-plan.md，并把相关 E2E 命令写进 test_command 或 release 验证链路",
         "确认每个 feature_impl 任务都携带 architecture_constraints、forbidden_implementations、tdd_contract 和项目真实可执行的 test_command",
         "明确哪些故事必须串行，哪些依赖可在后续手工改成并行"
@@ -364,6 +367,8 @@
         "dev-plan、verify-matrix 和 story 级执行顺序保持一致",
         "每个 feature_impl 的 tdd_contract.red.source_case_ids 均能回溯到 NATURAL_LANGUAGE_TEST_CASES.md",
         "每个 feature_impl 的非 TDD 自然语言用例均能回溯到 story_full_chain、acceptance_validation、回归计划或 verify-matrix",
+        "模板 phase 没有被压缩；如存在压缩或跨层混合，已附带用户批准的 decomposition_exemption",
+        "每个 feature_impl 默认不超过 3 条主 requirement_ids，且订单、支付、库存、RBAC 已拆成独立任务",
         "高风险用户可见任务已经明确是否需要 e2e-plan 与对应 E2E 证据",
         "实现任务不会把测试替身、local-only adapter 或领域原型伪装成声明的交付路径",
         "后续实现与 release 任务的验证边界已经明确且可执行"
@@ -487,19 +492,21 @@
         ],
         "exemptions": []
       },
-      "context_files": [
-        "docs/product/prd-lite.md",
-        "docs/product/requirement-interface-matrix.md",
-        "docs/architecture/constraints.md",
-        "docs/context/feature-pack.md",
-        "docs/design/design-brief.md",
-        "docs/design/component-map.md",
-        "docs/design/screen-states.md",
-        "docs/testing/ACCEPTANCE_EXAMPLES.md",
-        "docs/testing/NATURAL_LANGUAGE_TEST_CASES.md",
-        "docs/testing/TRACEABILITY_MATRIX.md",
-        "docs/testing/TEST_STRATEGY.md",
-        "docs/testing/TEST_DATA_MATRIX.md",
+      "context_files": [
+        "docs/product/prd-lite.md",
+        "docs/product/requirement-interface-matrix.md",
+        "docs/architecture/constraints.md",
+        "docs/context/feature-pack.md",
+        "docs/design/design-brief.md",
+        "docs/design/component-map.md",
+        "docs/design/screen-states.md",
+        "docs/testing/ACCEPTANCE_CRITERIA.md",
+        "docs/testing/ACCEPTANCE_EXAMPLES.md",
+        "docs/testing/NATURAL_LANGUAGE_TEST_CASES.md",
+        "docs/testing/REGRESSION_PLAN.md",
+        "docs/testing/TRACEABILITY_MATRIX.md",
+        "docs/testing/TEST_STRATEGY.md",
+        "docs/testing/TEST_DATA_MATRIX.md",
         "docs/testing/EVIDENCE_PROTOCOL.md",
         "docs/testing/test-matrix.md",
         "docs/testing/verify-matrix.md",
@@ -520,13 +527,14 @@
       "execution": {
         "mode": "single"
       },
-      "steps": [
-        "把 US1 标题、requirement_ids、owned_paths、产物路径和独立验证方式替换为真实项目内容",
-        "把 qa_contract 中的 tdd_contract.source_case_ids、story_full_chain.source_case_ids、acceptance_validation.source_case_ids、入口、数据、动作、Oracle、证据、失败态和 release impact 全部替换为真实内容",
-        "仅实现首个可单独交付的用户故事，并同步补齐其 affected tests 与必要文档",
-        "运行与 US1 对应的真实验证命令，必须包含开发验证和代码完成后的故事级验收链路，并记录可回溯证据"
-      ],
-      "test_command": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/verify.ps1 -Commands @('<replace-with-project-fitness-check>', '<replace-with-affected-tests>', 'git diff --check')",
+      "steps": [
+        "把 US1 标题、requirement_ids、owned_paths、产物路径和独立验证方式替换为真实项目内容",
+        "把 qa_contract 中的 tdd_contract.source_case_ids、story_full_chain.source_case_ids、acceptance_validation.source_case_ids、入口、数据、动作、Oracle、证据、失败态和 release impact 全部替换为真实内容",
+        "单个 feature_impl 默认不超过 3 条主 requirement_ids；订单、支付、库存、RBAC 不要和其他主故事捆绑；前端和后端不要长期混在同一个 story",
+        "仅实现首个可单独交付的用户故事，并同步补齐其 affected tests 与必要文档",
+        "运行与 US1 对应的真实验证命令，必须包含开发验证和代码完成后的故事级验收链路，并记录可回溯证据"
+      ],
+      "test_command": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\verify.ps1 -Commands @('<replace-with-project-fitness-check>', '<replace-with-affected-tests>', 'git diff --check')",
       "acceptance": [
         "US1 能作为 MVP 独立演示或独立验收",
         "US1 满足架构约束 truth source，不以测试替身冒充声明交付路径",
@@ -652,19 +660,21 @@
         ],
         "exemptions": []
       },
-      "context_files": [
-        "docs/product/prd-lite.md",
-        "docs/product/requirement-interface-matrix.md",
-        "docs/architecture/constraints.md",
-        "docs/context/feature-pack.md",
-        "docs/design/design-brief.md",
-        "docs/design/component-map.md",
-        "docs/design/screen-states.md",
-        "docs/testing/ACCEPTANCE_EXAMPLES.md",
-        "docs/testing/NATURAL_LANGUAGE_TEST_CASES.md",
-        "docs/testing/TRACEABILITY_MATRIX.md",
-        "docs/testing/TEST_STRATEGY.md",
-        "docs/testing/TEST_DATA_MATRIX.md",
+      "context_files": [
+        "docs/product/prd-lite.md",
+        "docs/product/requirement-interface-matrix.md",
+        "docs/architecture/constraints.md",
+        "docs/context/feature-pack.md",
+        "docs/design/design-brief.md",
+        "docs/design/component-map.md",
+        "docs/design/screen-states.md",
+        "docs/testing/ACCEPTANCE_CRITERIA.md",
+        "docs/testing/ACCEPTANCE_EXAMPLES.md",
+        "docs/testing/NATURAL_LANGUAGE_TEST_CASES.md",
+        "docs/testing/REGRESSION_PLAN.md",
+        "docs/testing/TRACEABILITY_MATRIX.md",
+        "docs/testing/TEST_STRATEGY.md",
+        "docs/testing/TEST_DATA_MATRIX.md",
         "docs/testing/EVIDENCE_PROTOCOL.md",
         "docs/testing/test-matrix.md",
         "docs/testing/verify-matrix.md",
@@ -685,13 +695,14 @@
       "execution": {
         "mode": "single"
       },
-      "steps": [
-        "将 US2 占位内容替换为真实范围、路径、需求编号和验证命令",
-        "把 qa_contract 中的 tdd_contract.source_case_ids、story_full_chain.source_case_ids、acceptance_validation.source_case_ids、入口、数据、动作、Oracle、证据、失败态和 release impact 全部替换为真实内容",
-        "确保 US2 可作为独立增量交付，不把未确认范围混入同一任务",
-        "补齐 US2 的 affected tests、开发验证、代码完成后的故事级验收链路、回归说明和证据路径"
-      ],
-      "test_command": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/verify.ps1 -Commands @('<replace-with-project-fitness-check>', '<replace-with-affected-tests>', 'git diff --check')",
+      "steps": [
+        "将 US2 占位内容替换为真实范围、路径、需求编号和验证命令",
+        "把 qa_contract 中的 tdd_contract.source_case_ids、story_full_chain.source_case_ids、acceptance_validation.source_case_ids、入口、数据、动作、Oracle、证据、失败态和 release impact 全部替换为真实内容",
+        "单个 feature_impl 默认不超过 3 条主 requirement_ids；订单、支付、库存、RBAC 不要和其他主故事捆绑；前端和后端不要长期混在同一个 story",
+        "确保 US2 可作为独立增量交付，不把未确认范围混入同一任务",
+        "补齐 US2 的 affected tests、开发验证、代码完成后的故事级验收链路、回归说明和证据路径"
+      ],
+      "test_command": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\verify.ps1 -Commands @('<replace-with-project-fitness-check>', '<replace-with-affected-tests>', 'git diff --check')",
       "acceptance": [
         "US2 范围清晰且不与其他故事混杂",
         "US2 满足架构约束 truth source，不以测试替身冒充声明交付路径",
@@ -817,18 +828,21 @@
         ],
         "exemptions": []
       },
-      "context_files": [
-        "docs/product/prd-lite.md",
-        "docs/product/requirement-interface-matrix.md",
-        "docs/architecture/constraints.md",
-        "docs/context/feature-pack.md",
-        "docs/design/design-brief.md",
-        "docs/design/component-map.md",
-        "docs/design/screen-states.md",
-        "docs/testing/ACCEPTANCE_EXAMPLES.md",
-        "docs/testing/TRACEABILITY_MATRIX.md",
-        "docs/testing/TEST_STRATEGY.md",
-        "docs/testing/TEST_DATA_MATRIX.md",
+      "context_files": [
+        "docs/product/prd-lite.md",
+        "docs/product/requirement-interface-matrix.md",
+        "docs/architecture/constraints.md",
+        "docs/context/feature-pack.md",
+        "docs/design/design-brief.md",
+        "docs/design/component-map.md",
+        "docs/design/screen-states.md",
+        "docs/testing/ACCEPTANCE_CRITERIA.md",
+        "docs/testing/ACCEPTANCE_EXAMPLES.md",
+        "docs/testing/NATURAL_LANGUAGE_TEST_CASES.md",
+        "docs/testing/REGRESSION_PLAN.md",
+        "docs/testing/TRACEABILITY_MATRIX.md",
+        "docs/testing/TEST_STRATEGY.md",
+        "docs/testing/TEST_DATA_MATRIX.md",
         "docs/testing/EVIDENCE_PROTOCOL.md",
         "docs/testing/test-matrix.md",
         "docs/testing/verify-matrix.md",
@@ -849,13 +863,14 @@
       "execution": {
         "mode": "single"
       },
-      "steps": [
-        "将 US3 占位内容替换为真实故事标题、路径、需求编号和验证方式",
-        "把 qa_contract 中的 tdd_contract.source_case_ids、story_full_chain.source_case_ids、acceptance_validation.source_case_ids、入口、数据、动作、Oracle、证据、失败态和 release impact 全部替换为真实内容",
-        "只承接剩余优先级最高且可单独验收的增量，不把 release 收口动作混入本故事",
-        "完成 US3 的实现、测试映射、开发验证、代码完成后的故事级验收链路和证据沉淀"
-      ],
-      "test_command": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/verify.ps1 -Commands @('<replace-with-project-fitness-check>', '<replace-with-affected-tests>', 'git diff --check')",
+      "steps": [
+        "将 US3 占位内容替换为真实故事标题、路径、需求编号和验证方式",
+        "把 qa_contract 中的 tdd_contract.source_case_ids、story_full_chain.source_case_ids、acceptance_validation.source_case_ids、入口、数据、动作、Oracle、证据、失败态和 release impact 全部替换为真实内容",
+        "单个 feature_impl 默认不超过 3 条主 requirement_ids；订单、支付、库存、RBAC 不要和其他主故事捆绑；前端和后端不要长期混在同一个 story",
+        "只承接剩余优先级最高且可单独验收的增量，不把 release 收口动作混入本故事",
+        "完成 US3 的实现、测试映射、开发验证、代码完成后的故事级验收链路和证据沉淀"
+      ],
+      "test_command": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\verify.ps1 -Commands @('<replace-with-project-fitness-check>', '<replace-with-affected-tests>', 'git diff --check')",
       "acceptance": [
         "US3 的增量边界和独立验收方式已明确",
         "US3 满足架构约束 truth source，不以测试替身冒充声明交付路径",

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

@@ -37,7 +37,7 @@
     }
   ],
   "runtime": {
-    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/codex-loop.ps1",
+    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\codex-loop.ps1",
     "run_profile": ".codex\\task-run-profile.json",
     "session": {
       "mode": "fresh-process",

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

@@ -1,6 +1,6 @@
 {
   "runtime": {
-    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/codex-loop.ps1",
+    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\codex-loop.ps1",
     "trace_dir": "traces",
     "agent": "codex",
     "run_profile": ".codex\\task-run-profile.json",

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

@@ -11,7 +11,7 @@ if ([string]::IsNullOrWhiteSpace($ProjectRoot)) {
   $ProjectRoot = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot "..\.."))
 }
 
-function Invoke-VerificationCommand {
+function Invoke-VerificationCommand {
   param(
     [string]$Command,
     [string]$Root
@@ -27,8 +27,22 @@ function Invoke-VerificationCommand {
   }
   finally {
     Pop-Location
-  }
-}
+  }
+}
+
+function Invoke-TaskStructureValidation {
+  param([string]$Root)
+
+  $scriptPath = Join-Path $Root "tools\harness\task-structure-lint.ps1"
+  if (-not (Test-Path -LiteralPath $scriptPath)) {
+    throw "缺少 task structure lint: tools\\harness\\task-structure-lint.ps1"
+  }
+
+  & powershell -NoProfile -ExecutionPolicy Bypass -File $scriptPath -ProjectRoot $Root | Out-Host
+  if ($LASTEXITCODE -ne 0) {
+    throw "task structure 校验失败。"
+  }
+}
 
 function Get-CodexHookCommand {
   param(
@@ -166,15 +180,17 @@ function Test-CodexHookCommandCompatibility {
 function Test-PowerShellSyntax {
   param([string]$Root)
 
-  $paths = @(
+  $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\task-structure-lint.ps1",
     "tools\harness\verify.ps1",
     "docs\codex-harness-engineering\templates\bootstrap-codex-harness.ps1",
-    "docs\codex-harness-engineering\templates\hooks\hook-stop-verify.ps1"
+    "docs\codex-harness-engineering\templates\hooks\hook-stop-verify.ps1",
+    "docs\codex-harness-engineering\templates\tools\harness\task-structure-lint.ps1"
   )
 
   foreach ($relativePath in $paths) {
@@ -273,13 +289,14 @@ function Invoke-AgentPackageFreshnessCheck {
 
 $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
+foreach ($command in $Commands) {
+  Invoke-VerificationCommand -Command $command -Root $resolvedProjectRoot
+}
+
+Invoke-TaskStructureValidation -Root $resolvedProjectRoot
+Test-CodexHookCommandCompatibility -Root $resolvedProjectRoot -AdditionalPaths $HookConfigPaths
+Test-PowerShellSyntax -Root $resolvedProjectRoot
+Test-NoStaleFeedbackMcpReferences -Root $resolvedProjectRoot
 Invoke-AgentPackageFreshnessCheck -Root $resolvedProjectRoot
 
 Write-Output "Verification passed."

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

@@ -0,0 +1,399 @@
+param(
+  [string]$ProjectRoot = "",
+  [string]$TaskFile = "task.json",
+  [switch]$JsonOutput
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+if ([string]::IsNullOrWhiteSpace($ProjectRoot)) {
+  $candidateRoots = @(
+    [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot "..\..")),
+    [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot "..\..\..\..\.."))
+  )
+
+  foreach ($candidateRoot in $candidateRoots | Select-Object -Unique) {
+    if (Test-Path -LiteralPath (Join-Path $candidateRoot "task.json")) {
+      $ProjectRoot = $candidateRoot
+      break
+    }
+  }
+
+  if ([string]::IsNullOrWhiteSpace($ProjectRoot)) {
+    $ProjectRoot = $candidateRoots[0]
+  }
+}
+
+$script:Findings = New-Object System.Collections.Generic.List[object]
+
+function Get-ObjectPropertyValue {
+  param(
+    [object]$InputObject,
+    [string]$Name,
+    [object]$Default = $null
+  )
+
+  if ($null -eq $InputObject) {
+    return $Default
+  }
+
+  $property = $InputObject.PSObject.Properties[$Name]
+  if ($null -eq $property) {
+    return $Default
+  }
+
+  return $property.Value
+}
+
+function ConvertTo-StringArray {
+  param([object]$Value)
+
+  if ($null -eq $Value) {
+    return @()
+  }
+
+  if ($Value -is [string]) {
+    if ([string]::IsNullOrWhiteSpace($Value)) {
+      return @()
+    }
+
+    return @([string]$Value)
+  }
+
+  $items = @()
+  foreach ($item in $Value) {
+    if ($null -ne $item -and -not [string]::IsNullOrWhiteSpace([string]$item)) {
+      $items += [string]$item
+    }
+  }
+
+  return $items
+}
+
+function Add-Finding {
+  param(
+    [string]$Severity,
+    [string]$Code,
+    [string]$Message,
+    [string]$TaskId = "",
+    [string]$Field = ""
+  )
+
+  $script:Findings.Add([pscustomobject]@{
+      severity = $Severity
+      code = $Code
+      message = $Message
+      task_id = $TaskId
+      field = $Field
+    })
+}
+
+function Read-JsonFileOrNull {
+  param([string]$Path)
+
+  try {
+    return (Get-Content -LiteralPath $Path -Raw | ConvertFrom-Json)
+  }
+  catch {
+    return $null
+  }
+}
+
+function Get-TaskList {
+  param([object]$TaskDocument)
+
+  $tasks = Get-ObjectPropertyValue -InputObject $TaskDocument -Name "tasks" -Default $null
+  if ($null -eq $tasks -or ($tasks -is [string]) -or (-not ($tasks -is [System.Collections.IEnumerable]))) {
+    return @()
+  }
+
+  return @($tasks)
+}
+
+function Test-FileExists {
+  param(
+    [string]$Root,
+    [string]$RelativePath
+  )
+
+  return (Test-Path -LiteralPath (Join-Path $Root $RelativePath))
+}
+
+function Test-IsFormalTaskQueue {
+  param([object[]]$Tasks)
+
+  foreach ($task in @($Tasks)) {
+    $taskKind = [string](Get-ObjectPropertyValue -InputObject $task -Name "task_kind" -Default "")
+    if (@("feature_research", "feature_spec", "feature_design", "feature_plan", "feature_impl", "release", "archive") -contains $taskKind) {
+      return $true
+    }
+  }
+
+  return $false
+}
+
+function Test-ApprovedDecompositionExemption {
+  param(
+    [object]$Task,
+    [string]$Scope
+  )
+
+  $exemption = Get-ObjectPropertyValue -InputObject $Task -Name "decomposition_exemption" -Default $null
+  if ($null -eq $exemption) {
+    return $false
+  }
+
+  $approved = [bool](Get-ObjectPropertyValue -InputObject $exemption -Name "user_approved" -Default $false)
+  if (-not $approved) {
+    return $false
+  }
+
+  $scopes = @(ConvertTo-StringArray -Value (Get-ObjectPropertyValue -InputObject $exemption -Name "scopes" -Default @()))
+  if ($scopes.Count -eq 0) {
+    return $true
+  }
+
+  return $scopes -contains $Scope
+}
+
+function Get-OwnedSurfaceKinds {
+  param([string[]]$OwnedPaths)
+
+  $hasBackend = $false
+  $hasFrontend = $false
+
+  foreach ($rawPath in @($OwnedPaths)) {
+    $path = $rawPath.Replace('/', '\').ToLowerInvariant()
+    if ($path -match '(^|\\)(apps\\api|backend|server|services?)($|\\)') {
+      $hasBackend = $true
+    }
+
+    if ($path -match '(^|\\)(apps\\admin|apps\\web|apps\\mobile|frontend|web|mobile|ui)($|\\)') {
+      $hasFrontend = $true
+    }
+  }
+
+  return [pscustomobject]@{
+    backend = $hasBackend
+    frontend = $hasFrontend
+  }
+}
+
+function Get-DomainMatches {
+  param([object]$Task)
+
+  $description = [string](Get-ObjectPropertyValue -InputObject $Task -Name "description" -Default "")
+  $steps = ConvertTo-StringArray -Value (Get-ObjectPropertyValue -InputObject $Task -Name "steps" -Default @())
+  $requirementIds = ConvertTo-StringArray -Value (Get-ObjectPropertyValue -InputObject $Task -Name "requirement_ids" -Default @())
+  $haystack = (($description + " " + ($steps -join " ") + " " + ($requirementIds -join " ")).ToLowerInvariant())
+
+  $domainMatchesList = @()
+  $patterns = @(
+    @{ name = "order"; pattern = '(订单|order)' },
+    @{ name = "payment"; pattern = '(支付|payment)' },
+    @{ name = "inventory"; pattern = '(库存|inventory)' },
+    @{ name = "rbac"; pattern = '(rbac|角色权限|权限角色|role[ -]?based access)' }
+  )
+
+  foreach ($entry in $patterns) {
+    if ($haystack -match $entry["pattern"]) {
+      $domainMatchesList += [string]$entry["name"]
+    }
+  }
+
+  return @($domainMatchesList | Select-Object -Unique)
+}
+
+function Test-RequiredSourceCaseIds {
+  param(
+    [object]$ParentObject,
+    [string]$PropertyName,
+    [string]$TaskId,
+    [string]$FieldBase
+  )
+
+  $target = Get-ObjectPropertyValue -InputObject $ParentObject -Name $PropertyName -Default $null
+  if ($null -eq $target) {
+    Add-Finding -Severity "error" -Code "missing_field" -Message "任务缺少 $FieldBase.$PropertyName。" -TaskId $TaskId -Field "$FieldBase.$PropertyName"
+    return
+  }
+
+  $sourceCaseIds = @(ConvertTo-StringArray -Value (Get-ObjectPropertyValue -InputObject $target -Name "source_case_ids" -Default @()))
+  if ($sourceCaseIds.Count -eq 0) {
+    Add-Finding -Severity "error" -Code "empty_source_case_ids" -Message "任务缺少 $FieldBase.$PropertyName.source_case_ids。" -TaskId $TaskId -Field "$FieldBase.$PropertyName.source_case_ids"
+  }
+}
+
+function Test-FormalTaskQueueStructure {
+  param(
+    [string]$Root,
+    [object[]]$Tasks
+  )
+
+  $taskIdSet = @{}
+  foreach ($task in @($Tasks)) {
+    $taskId = [string](Get-ObjectPropertyValue -InputObject $task -Name "id" -Default "")
+    if (-not [string]::IsNullOrWhiteSpace($taskId)) {
+      $taskIdSet[$taskId] = $true
+    }
+  }
+
+  foreach ($requiredTaskId in @("ANALYSIS-001", "TESTCASE-001", "PLAN-001")) {
+    if (-not $taskIdSet.ContainsKey($requiredTaskId)) {
+      Add-Finding -Severity "error" -Code "missing_phase_task" -Message "正式任务队列缺少必需 phase：$requiredTaskId。" -Field "tasks"
+    }
+  }
+
+  $featureImplTasks = @($Tasks | Where-Object { [string](Get-ObjectPropertyValue -InputObject $_ -Name "task_kind" -Default "") -eq "feature_impl" })
+  $releaseTasks = @($Tasks | Where-Object { [string](Get-ObjectPropertyValue -InputObject $_ -Name "task_kind" -Default "") -eq "release" })
+
+  if (($featureImplTasks.Count + $releaseTasks.Count) -gt 0) {
+    $requiredTestingArtifacts = @(
+      "docs\testing\ACCEPTANCE_CRITERIA.md",
+      "docs\testing\NATURAL_LANGUAGE_TEST_CASES.md",
+      "docs\testing\TRACEABILITY_MATRIX.md",
+      "docs\testing\TEST_DATA_MATRIX.md",
+      "docs\testing\REGRESSION_PLAN.md",
+      "docs\testing\verify-matrix.md"
+    )
+
+    foreach ($relativePath in $requiredTestingArtifacts) {
+      if (-not (Test-FileExists -Root $Root -RelativePath $relativePath)) {
+        Add-Finding -Severity "error" -Code "missing_testing_artifact" -Message "正式任务队列缺少测试真相源：$relativePath。" -Field $relativePath
+      }
+    }
+  }
+
+  foreach ($task in $featureImplTasks) {
+    $taskId = [string](Get-ObjectPropertyValue -InputObject $task -Name "id" -Default "")
+    $qaContract = Get-ObjectPropertyValue -InputObject $task -Name "qa_contract" -Default $null
+    if ($null -eq $qaContract) {
+      Add-Finding -Severity "error" -Code "missing_qa_contract" -Message "feature_impl 缺少 qa_contract。" -TaskId $taskId -Field "qa_contract"
+    }
+    else {
+      $requiredLayers = @(ConvertTo-StringArray -Value (Get-ObjectPropertyValue -InputObject $qaContract -Name "required_layers" -Default @()))
+      foreach ($layer in @("unit_or_component", "contract_or_api", "story_full_chain", "affected_regression")) {
+        if ($requiredLayers -notcontains $layer) {
+          Add-Finding -Severity "error" -Code "missing_required_layer" -Message "feature_impl 缺少 qa_contract.required_layers[$layer]。" -TaskId $taskId -Field "qa_contract.required_layers"
+        }
+      }
+
+      $developmentValidation = Get-ObjectPropertyValue -InputObject $qaContract -Name "development_validation" -Default $null
+      if ($null -eq $developmentValidation) {
+        Add-Finding -Severity "error" -Code "missing_development_validation" -Message "feature_impl 缺少 qa_contract.development_validation。" -TaskId $taskId -Field "qa_contract.development_validation"
+      }
+
+      $acceptanceValidation = Get-ObjectPropertyValue -InputObject $qaContract -Name "acceptance_validation" -Default $null
+      if ($null -eq $acceptanceValidation) {
+        Add-Finding -Severity "error" -Code "missing_acceptance_validation" -Message "feature_impl 缺少 qa_contract.acceptance_validation。" -TaskId $taskId -Field "qa_contract.acceptance_validation"
+      }
+
+      $tddContract = Get-ObjectPropertyValue -InputObject $qaContract -Name "tdd_contract" -Default $null
+      if ($null -eq $tddContract) {
+        Add-Finding -Severity "error" -Code "missing_tdd_contract" -Message "feature_impl 缺少 qa_contract.tdd_contract。" -TaskId $taskId -Field "qa_contract.tdd_contract"
+      }
+      else {
+        $red = Get-ObjectPropertyValue -InputObject $tddContract -Name "red" -Default $null
+        if ($null -eq $red) {
+          Add-Finding -Severity "error" -Code "missing_tdd_red" -Message "feature_impl 缺少 qa_contract.tdd_contract.red。" -TaskId $taskId -Field "qa_contract.tdd_contract.red"
+        }
+        else {
+          $sourceCaseIds = @(ConvertTo-StringArray -Value (Get-ObjectPropertyValue -InputObject $red -Name "source_case_ids" -Default @()))
+          if ($sourceCaseIds.Count -eq 0) {
+            Add-Finding -Severity "error" -Code "empty_source_case_ids" -Message "feature_impl 缺少 qa_contract.tdd_contract.red.source_case_ids。" -TaskId $taskId -Field "qa_contract.tdd_contract.red.source_case_ids"
+          }
+        }
+
+        foreach ($requiredField in @("green", "refactor_guard")) {
+          if ($null -eq (Get-ObjectPropertyValue -InputObject $tddContract -Name $requiredField -Default $null)) {
+            Add-Finding -Severity "error" -Code "missing_tdd_field" -Message "feature_impl 缺少 qa_contract.tdd_contract.$requiredField。" -TaskId $taskId -Field "qa_contract.tdd_contract.$requiredField"
+          }
+        }
+      }
+
+      Test-RequiredSourceCaseIds -ParentObject $qaContract -PropertyName "story_full_chain" -TaskId $taskId -FieldBase "qa_contract"
+      if ($null -ne $acceptanceValidation) {
+        $acceptanceSourceCaseIds = @(ConvertTo-StringArray -Value (Get-ObjectPropertyValue -InputObject $acceptanceValidation -Name "source_case_ids" -Default @()))
+        if ($acceptanceSourceCaseIds.Count -eq 0) {
+          Add-Finding -Severity "error" -Code "empty_source_case_ids" -Message "feature_impl 缺少 qa_contract.acceptance_validation.source_case_ids。" -TaskId $taskId -Field "qa_contract.acceptance_validation.source_case_ids"
+        }
+      }
+    }
+
+    $requirementIds = @(ConvertTo-StringArray -Value (Get-ObjectPropertyValue -InputObject $task -Name "requirement_ids" -Default @()))
+    if ($requirementIds.Count -gt 3 -and -not (Test-ApprovedDecompositionExemption -Task $task -Scope "requirement_span")) {
+      Add-Finding -Severity "error" -Code "oversized_requirement_span" -Message "单个 feature_impl 默认不得覆盖超过 3 条主 requirement_ids。" -TaskId $taskId -Field "requirement_ids"
+    }
+
+    $ownedPaths = @(ConvertTo-StringArray -Value (Get-ObjectPropertyValue -InputObject $task -Name "owned_paths" -Default @()))
+    $surfaceKinds = Get-OwnedSurfaceKinds -OwnedPaths $ownedPaths
+    if ($surfaceKinds.backend -and $surfaceKinds.frontend -and -not (Test-ApprovedDecompositionExemption -Task $task -Scope "mixed_surface")) {
+      Add-Finding -Severity "error" -Code "mixed_frontend_backend_story" -Message "feature_impl 同时覆盖前端与后端路径；请拆分为独立 story 或改为明确的 release 收口。" -TaskId $taskId -Field "owned_paths"
+    }
+
+    $domains = @(Get-DomainMatches -Task $task)
+    if ($domains.Count -gt 1 -and -not (Test-ApprovedDecompositionExemption -Task $task -Scope "domain_bundle")) {
+      Add-Finding -Severity "error" -Code "combined_high_risk_domains" -Message ("feature_impl 同时覆盖高风险主域：{0}。订单、支付、库存、RBAC 必须拆独立任务。" -f ($domains -join ", ")) -TaskId $taskId -Field "description"
+    }
+  }
+}
+
+$resolvedProjectRoot = (Resolve-Path -LiteralPath $ProjectRoot).Path
+$taskPath = Join-Path $resolvedProjectRoot $TaskFile
+
+if (-not (Test-Path -LiteralPath $taskPath)) {
+  Add-Finding -Severity "error" -Code "missing_task_file" -Message "缺少 task.json：$TaskFile。" -Field $TaskFile
+}
+else {
+  $taskDocument = Read-JsonFileOrNull -Path $taskPath
+  if ($null -eq $taskDocument) {
+    Add-Finding -Severity "error" -Code "invalid_task_json" -Message "task.json 不是合法 JSON。" -Field $TaskFile
+  }
+  else {
+    $tasks = Get-TaskList -TaskDocument $taskDocument
+    if ($tasks.Count -eq 0) {
+      Add-Finding -Severity "error" -Code "empty_task_queue" -Message "task.json 不包含可校验任务。" -Field "tasks"
+    }
+    elseif (Test-IsFormalTaskQueue -Tasks $tasks) {
+      Test-FormalTaskQueueStructure -Root $resolvedProjectRoot -Tasks $tasks
+    }
+  }
+}
+
+$errors = @($script:Findings | Where-Object { $_.severity -eq "error" })
+$warnings = @($script:Findings | Where-Object { $_.severity -eq "warning" })
+$status = if ($errors.Count -gt 0) { "fail" } elseif ($warnings.Count -gt 0) { "warn" } else { "pass" }
+$result = @{
+  status = $status
+  error_count = $errors.Count
+  warning_count = $warnings.Count
+  findings = @($script:Findings.ToArray())
+}
+
+if ($JsonOutput) {
+  $result | ConvertTo-Json -Depth 8
+}
+else {
+  if ($status -eq "fail") {
+    Write-Output "Task structure validation failed."
+  }
+  elseif ($status -eq "warn") {
+    Write-Output "Task structure validation passed with warnings."
+  }
+  else {
+    Write-Output "Task structure validation passed."
+  }
+
+  foreach ($finding in $script:Findings.ToArray()) {
+    $taskLabel = if ([string]::IsNullOrWhiteSpace([string]$finding.task_id)) { "" } else { " task=$($finding.task_id)" }
+    $fieldLabel = if ([string]::IsNullOrWhiteSpace([string]$finding.field)) { "" } else { " field=$($finding.field)" }
+    Write-Output "- [$($finding.severity)] $($finding.code)$taskLabel$fieldLabel :: $($finding.message)"
+  }
+}
+
+if ($status -eq "fail") {
+  exit 1
+}
+
+exit 0

package/package-source/install-manifest.json

@@ -2,7 +2,7 @@
   "schemaVersion": "0.1",
   "status": "draft",
   "package": "codex-harness",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "installModes": [
     {
       "name": "user",

package/package-source/tools/install/bootstrap-codex-harness.ps1

@@ -225,16 +225,28 @@ function Ensure-TaskFile {
     return Copy-ManagedFile -SourceRoot $SourceRoot -SourceRelativePath "runtime\task.json" -DestinationRoot $DestinationRoot -DestinationRelativePath "task.json" -Overwrite:$true
   }
 
-  $taskDocument = $taskContent | ConvertFrom-Json
-  if ($null -eq $taskDocument.runtime) {
-    $taskDocument | Add-Member -NotePropertyName "runtime" -NotePropertyValue ([PSCustomObject]@{}) -Force
-  }
-
-  if ([string]::IsNullOrWhiteSpace($taskDocument.runtime.driver)) {
-    $taskDocument.runtime.driver = "powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\codex-loop.ps1"
-    $taskDocument | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $taskPath -Encoding UTF8
-    return [PSCustomObject]@{
-      Path = $taskPath
+  $taskDocument = $taskContent | ConvertFrom-Json
+  if ($null -eq $taskDocument.runtime) {
+    $taskDocument | Add-Member -NotePropertyName "runtime" -NotePropertyValue ([PSCustomObject]@{}) -Force
+  }
+
+  $canonicalDriver = "powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\codex-loop.ps1"
+  $driverPattern = 'tools[\\/]+harness[\\/]+tools[\\/]+harness[\\/]+codex-loop\.ps1'
+
+  if ([string]::IsNullOrWhiteSpace($taskDocument.runtime.driver)) {
+    $taskDocument.runtime.driver = $canonicalDriver
+    $taskDocument | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $taskPath -Encoding UTF8
+    return [PSCustomObject]@{
+      Path = $taskPath
+      Action = "updated"
+    }
+  }
+
+  if ([string]$taskDocument.runtime.driver -match $driverPattern) {
+    $taskDocument.runtime.driver = $canonicalDriver
+    $taskDocument | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $taskPath -Encoding UTF8
+    return [PSCustomObject]@{
+      Path = $taskPath
       Action = "updated"
     }
   }
@@ -601,6 +613,7 @@ $rootFiles = @(
   @{ Source = "prompts\worker-role\harness-writer.md"; Destination = ".codex\prompts\worker-role\harness-writer.md" },
   @{ Source = "runtime\smoke-task.json"; Destination = "tools\harness\templates\smoke-task.json" },
   @{ Source = "runtime\project-task-template.json"; Destination = "tools\harness\templates\project-task-template.json" },
+  @{ Source = "tools\harness\task-structure-lint.ps1"; Destination = "tools\harness\task-structure-lint.ps1" },
   @{ Source = "runtime\verify.ps1"; Destination = "tools\harness\verify.ps1" },
   @{ Source = "tools\harness\docs-lint.ps1"; Destination = "tools\harness\docs-lint.ps1" },
   @{ Source = "tools\harness\data-lint.ps1"; Destination = "tools\harness\data-lint.ps1" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pzy560117/codex-harness",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Codex Harness installer and project runtime CLI",
   "type": "module",
   "bin": {