@pzy560117/codex-harness 0.1.6 → 0.1.8

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.5",
+  "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.6",
+  "version": "0.1.8",
   "description": "Codex Harness installer and project runtime CLI",
   "type": "module",
   "bin": {