@pzy560117/codex-harness 0.1.0 → 0.1.1

package/package-source/docs/codex-harness-engineering/templates/scripts/ai-workflow/check-ai-sync-drift.ps1

@@ -0,0 +1,205 @@
+param(
+  [string]$ProjectRoot = "",
+  [string]$SyncFile = ".ai-sync.yml",
+  [string]$ManifestPath = "ai-sync/ai-kit-manifest.json",
+  [string]$LockPath = ".ai-sync.lock.json"
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+if ([string]::IsNullOrWhiteSpace($ProjectRoot)) {
+  $currentLocationRoot = (Get-Location).Path
+  $scriptDerivedRoot = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot "..\.."))
+  if (Test-Path -LiteralPath (Join-Path $currentLocationRoot $SyncFile) -PathType Leaf) {
+    $ProjectRoot = $currentLocationRoot
+  }
+  elseif (Test-Path -LiteralPath (Join-Path $scriptDerivedRoot $SyncFile) -PathType Leaf) {
+    $ProjectRoot = $scriptDerivedRoot
+  }
+  else {
+    $ProjectRoot = $currentLocationRoot
+  }
+}
+
+function Normalize-RelativePath {
+  param(
+    [Parameter(Mandatory = $true)]
+    [string]$Path,
+    [switch]$Directory
+  )
+
+  $normalized = $Path.Replace("\", "/").Trim()
+  while ($normalized.StartsWith("./", [System.StringComparison]::Ordinal)) {
+    $normalized = $normalized.Substring(2)
+  }
+
+  if ($Directory) {
+    return $normalized.TrimEnd("/") + "/"
+  }
+
+  return $normalized.TrimEnd("/")
+}
+
+function Join-NormalizedRelativePath {
+  param(
+    [string]$Base,
+    [string]$Child
+  )
+
+  $left = Normalize-RelativePath -Path $Base
+  $right = Normalize-RelativePath -Path $Child
+  if ([string]::IsNullOrWhiteSpace($left)) {
+    return $right
+  }
+  if ([string]::IsNullOrWhiteSpace($right)) {
+    return $left
+  }
+
+  return "{0}/{1}" -f $left.TrimEnd("/"), $right
+}
+
+function Get-RelativePathFromRoot {
+  param(
+    [string]$Root,
+    [string]$TargetPath
+  )
+
+  $rootFull = [System.IO.Path]::GetFullPath($Root).TrimEnd("\", "/") + [System.IO.Path]::DirectorySeparatorChar
+  $targetFull = [System.IO.Path]::GetFullPath($TargetPath)
+  if (-not $targetFull.StartsWith($rootFull, [System.StringComparison]::OrdinalIgnoreCase)) {
+    throw "路径不在项目根目录内: $TargetPath"
+  }
+
+  return Normalize-RelativePath -Path $targetFull.Substring($rootFull.Length)
+}
+
+function Read-JsonConfig {
+  param(
+    [string]$Path,
+    [string]$Label
+  )
+
+  if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+    throw "找不到 ${Label}: $Path"
+  }
+
+  try {
+    return Get-Content -LiteralPath $Path -Raw | ConvertFrom-Json
+  }
+  catch {
+    throw "${Label} 需要使用 JSON 兼容格式，当前文件无法用 ConvertFrom-Json 解析: $Path"
+  }
+}
+
+function Get-FileSha256 {
+  param([string]$Path)
+  return (Get-FileHash -LiteralPath $Path -Algorithm SHA256).Hash.ToLowerInvariant()
+}
+
+$resolvedProjectRoot = (Resolve-Path -LiteralPath $ProjectRoot).Path
+$resolvedSyncFile = Join-Path $resolvedProjectRoot $SyncFile
+$resolvedManifestPath = Join-Path $resolvedProjectRoot $ManifestPath
+$resolvedLockPath = Join-Path $resolvedProjectRoot $LockPath
+
+if (-not (Test-Path -LiteralPath $resolvedSyncFile -PathType Leaf)) {
+  Write-Output "No .ai-sync.yml found. Skip AI sync drift check."
+  exit 0
+}
+
+$config = Read-JsonConfig -Path $resolvedSyncFile -Label ".ai-sync.yml"
+$manifest = Read-JsonConfig -Path $resolvedManifestPath -Label "ai-kit-manifest"
+$lock = Read-JsonConfig -Path $resolvedLockPath -Label ".ai-sync.lock.json"
+
+$currentManifestHash = Get-FileSha256 -Path $resolvedManifestPath
+$expectedManifestPath = Normalize-RelativePath -Path $ManifestPath
+$failures = New-Object System.Collections.Generic.List[string]
+
+if ([string]$lock.manifest.path -ne $expectedManifestPath) {
+  $failures.Add("Lock manifest path mismatch: expected $expectedManifestPath actual $($lock.manifest.path)")
+}
+
+if ([string]$lock.manifest.sha256 -ne $currentManifestHash) {
+  $failures.Add("Lock manifest hash mismatch: expected $($lock.manifest.sha256) actual $currentManifestHash")
+}
+
+$sourceHash = @{}
+foreach ($item in $manifest.files) {
+  $sourceHash[(Normalize-RelativePath -Path ([string]$item.source))] = [string]$item.sha256
+}
+
+foreach ($mapping in $config.managed) {
+  $mappingType = if ([string]::IsNullOrWhiteSpace($mapping.type)) { "directory" } else { [string]$mapping.type }
+  $source = Normalize-RelativePath -Path ([string]$mapping.source) -Directory:($mappingType -eq "directory")
+  $destination = Normalize-RelativePath -Path ([string]$mapping.dest) -Directory:($mappingType -eq "directory")
+
+  if ($mappingType -eq "file") {
+    $expectedHash = $sourceHash[(Normalize-RelativePath -Path $source)]
+    if ([string]::IsNullOrWhiteSpace($expectedHash)) {
+      $failures.Add("Manifest missing source file: $source")
+      continue
+    }
+
+    $targetPath = Join-Path $resolvedProjectRoot $destination
+    if (-not (Test-Path -LiteralPath $targetPath -PathType Leaf)) {
+      $failures.Add("Missing managed file: $destination")
+      continue
+    }
+
+    $actualHash = Get-FileSha256 -Path $targetPath
+    if ($actualHash -ne $expectedHash) {
+      $failures.Add("Drift detected: $destination`n  expected $expectedHash`n  actual   $actualHash")
+    }
+    continue
+  }
+
+  $sourcePrefix = $source
+  $destinationRoot = Join-Path $resolvedProjectRoot $destination
+  $expectedDestinations = @{}
+
+  foreach ($item in $manifest.files) {
+    $itemSource = Normalize-RelativePath -Path ([string]$item.source)
+    if (-not $itemSource.StartsWith($sourcePrefix, [System.StringComparison]::Ordinal)) {
+      continue
+    }
+
+    $relative = $itemSource.Substring($sourcePrefix.Length)
+    $targetRelative = Join-NormalizedRelativePath -Base $destination -Child $relative
+    $expectedDestinations[$targetRelative] = $true
+
+    $targetPath = Join-Path $destinationRoot ($relative.Replace("/", "\"))
+    if (-not (Test-Path -LiteralPath $targetPath -PathType Leaf)) {
+      $failures.Add("Missing managed file: $targetRelative")
+      continue
+    }
+
+    $actualHash = Get-FileSha256 -Path $targetPath
+    $expectedHash = [string]$item.sha256
+    if ($actualHash -ne $expectedHash) {
+      $failures.Add("Drift detected: $targetRelative`n  expected $expectedHash`n  actual   $actualHash")
+    }
+  }
+
+  if (Test-Path -LiteralPath $destinationRoot -PathType Container) {
+    foreach ($file in Get-ChildItem -LiteralPath $destinationRoot -Recurse -File) {
+      $targetRelative = Get-RelativePathFromRoot -Root $resolvedProjectRoot -TargetPath $file.FullName
+      if (-not $expectedDestinations.ContainsKey($targetRelative)) {
+        $failures.Add("Unexpected managed file: $targetRelative")
+      }
+    }
+  }
+}
+
+if ($failures.Count -gt 0) {
+  Write-Output "AI config drift detected."
+  Write-Output ""
+  foreach ($failure in $failures) {
+    Write-Output ("- {0}" -f $failure)
+  }
+  Write-Output ""
+  Write-Output "Do not edit managed files directly."
+  Write-Output "Use .ai-overrides/ for project-specific changes, or update the central ai-workflow-kit repository."
+  exit 1
+}
+
+Write-Output "AI config drift check passed."

package/package-source/docs/codex-harness-engineering/templates/scripts/harness/harness-governance-check.ps1

@@ -0,0 +1,366 @@
+param(
+  [string]$ProjectRoot = (Get-Location).Path,
+  [switch]$WriteExperience
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+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 Add-Finding {
+  param(
+    [System.Collections.Generic.List[object]]$Findings,
+    [string]$Severity,
+    [string]$Category,
+    [string]$Message,
+    [string]$RepairMode,
+    [string]$TargetDoc = "docs/harness/governance-auto-repair.md"
+  )
+
+  $Findings.Add([pscustomobject]@{
+    severity = $Severity
+    category = $Category
+    message = $Message
+    repair_mode = $RepairMode
+    target_doc = $TargetDoc
+  })
+}
+
+function Get-RelativePathCompat {
+  param(
+    [string]$Root,
+    [string]$Path
+  )
+
+  $rootFull = ([System.IO.Path]::GetFullPath($Root)).TrimEnd('\', '/') + '\'
+  $pathFull = [System.IO.Path]::GetFullPath($Path)
+  if ($pathFull.StartsWith($rootFull, [System.StringComparison]::OrdinalIgnoreCase)) {
+    return $pathFull.Substring($rootFull.Length).Replace('\', '/')
+  }
+
+  return $pathFull.Replace('\', '/')
+}
+
+function Test-MergeMarkers {
+  param(
+    [string]$Root,
+    [System.Collections.Generic.List[object]]$Findings
+  )
+
+  $scanRoots = @(
+    "AGENTS.md",
+    ".codex",
+    "docs/harness",
+    "docs/codex-harness-engineering"
+  )
+
+  foreach ($scanRoot in $scanRoots) {
+    $fullPath = Join-Path $Root $scanRoot
+    if (-not (Test-Path -LiteralPath $fullPath)) {
+      continue
+    }
+
+    $files = if (Test-Path -LiteralPath $fullPath -PathType Leaf) {
+      @(Get-Item -LiteralPath $fullPath)
+    }
+    else {
+      @(Get-ChildItem -LiteralPath $fullPath -Recurse -File -Include *.md,*.json,*.toml,*.ps1,*.rules)
+    }
+
+    foreach ($file in $files) {
+      $content = Get-Content -LiteralPath $file.FullName -Raw -ErrorAction SilentlyContinue
+      if ($content -match '(?m)^(<<<<<<<|=======|>>>>>>>)') {
+        Add-Finding `
+          -Findings $Findings `
+          -Severity "block" `
+          -Category "merge_marker" `
+          -Message ("Merge marker found in {0}." -f (Get-RelativePathCompat -Root $Root -Path $file.FullName)) `
+          -RepairMode "agent_repair" `
+          -TargetDoc "docs/harness/rule-governance.md"
+      }
+    }
+  }
+}
+
+function Test-HookSurface {
+  param(
+    [string]$Root,
+    [System.Collections.Generic.List[object]]$Findings
+  )
+
+  $hookConfigPath = Join-Path $Root ".codex\hooks.json"
+  if (-not (Test-Path -LiteralPath $hookConfigPath)) {
+    return
+  }
+
+  $hookText = Get-Content -LiteralPath $hookConfigPath -Raw
+  if ($hookText.Contains("hook-stop-verify.ps1")) {
+    $activeScript = Join-Path $Root "scripts\harness\hook-stop-verify.ps1"
+    $templateScript = Join-Path $Root "docs\codex-harness-engineering\templates\hooks\hook-stop-verify.ps1"
+    $installedTemplateScript = Join-Path $Root ".agents\docs\codex-harness-engineering\templates\hooks\hook-stop-verify.ps1"
+
+    if (-not (Test-Path -LiteralPath $activeScript)) {
+      $repairMode = if ((Test-Path -LiteralPath $templateScript) -or (Test-Path -LiteralPath $installedTemplateScript)) {
+        "deterministic_repair"
+      }
+      else {
+        "agent_repair"
+      }
+
+      Add-Finding `
+        -Findings $Findings `
+        -Severity "block" `
+        -Category "missing_stop_hook_script" `
+        -Message "hooks.json references tools/harness/hook-stop-verify.ps1, but the script is missing." `
+        -RepairMode $repairMode `
+        -TargetDoc "docs/harness/governance-auto-repair.md"
+    }
+  }
+}
+
+function Test-RulesSurface {
+  param(
+    [string]$Root,
+    [System.Collections.Generic.List[object]]$Findings
+  )
+
+  $rulesDir = Join-Path $Root ".codex\rules"
+  if (-not (Test-Path -LiteralPath $rulesDir)) {
+    return
+  }
+
+  $rulesFiles = @(Get-ChildItem -LiteralPath $rulesDir -File -Filter "*.rules" -ErrorAction SilentlyContinue)
+  if ($rulesFiles.Count -eq 0) {
+    Add-Finding `
+      -Findings $Findings `
+      -Severity "warn" `
+      -Category "missing_execpolicy_rules" `
+      -Message ".codex/rules contains semantic Markdown rules but no official *.rules execution policy files." `
+      -RepairMode "deterministic_repair" `
+      -TargetDoc "docs/harness/rule-governance.md"
+  }
+}
+
+function Test-ConfigSurface {
+  param(
+    [string]$Root,
+    [System.Collections.Generic.List[object]]$Findings
+  )
+
+  $configPath = Join-Path $Root ".codex\config.toml"
+  if (-not (Test-Path -LiteralPath $configPath)) {
+    return
+  }
+
+  $configText = Get-Content -LiteralPath $configPath -Raw
+  if ($configText -match "project_doc_fallback_filenames") {
+    $hasAgents = Test-Path -LiteralPath (Join-Path $Root "AGENTS.md")
+    $hasTeamGuide = Test-Path -LiteralPath (Join-Path $Root "TEAM_GUIDE.md")
+    $hasDotAgents = Test-Path -LiteralPath (Join-Path $Root ".agents.md")
+    if ($hasAgents -and (-not $hasTeamGuide) -and (-not $hasDotAgents)) {
+      Add-Finding `
+        -Findings $Findings `
+        -Severity "warn" `
+        -Category "stale_fallback_config" `
+        -Message "project_doc_fallback_filenames is configured, but AGENTS.md exists and fallback files are missing." `
+        -RepairMode "agent_repair" `
+        -TargetDoc "docs/harness/rule-governance.md"
+    }
+  }
+}
+
+function Get-LatestTraceFile {
+  param([string]$Root)
+
+  $traceDir = Join-Path $Root "traces"
+  if (-not (Test-Path -LiteralPath $traceDir)) {
+    return $null
+  }
+
+  return @(Get-ChildItem -LiteralPath $traceDir -Recurse -File -Filter "*.json" -ErrorAction SilentlyContinue |
+    Sort-Object LastWriteTimeUtc -Descending |
+    Select-Object -First 1)[0]
+}
+
+function New-ExperienceFromTrace {
+  param([string]$Root)
+
+  $traceFile = Get-LatestTraceFile -Root $Root
+  if ($null -eq $traceFile) {
+    return $null
+  }
+
+  try {
+    $trace = Get-Content -LiteralPath $traceFile.FullName -Raw | ConvertFrom-Json
+  }
+  catch {
+    return $null
+  }
+
+  $status = [string](Get-ObjectPropertyValue -InputObject $trace -Name "status" -Default "")
+  if ($status -eq "passed") {
+    return $null
+  }
+
+  $taskId = [string](Get-ObjectPropertyValue -InputObject $trace -Name "task_id" -Default "unknown")
+  $failedStage = [string](Get-ObjectPropertyValue -InputObject $trace -Name "failed_stage" -Default "")
+  $blockedReason = [string](Get-ObjectPropertyValue -InputObject $trace -Name "blocked_reason" -Default "")
+  $relativeTrace = Get-RelativePathCompat -Root $Root -Path $traceFile.FullName
+  $summary = "Task $taskId ended with status=$status"
+  if (-not [string]::IsNullOrWhiteSpace($failedStage)) {
+    $summary += ", failed_stage=$failedStage"
+  }
+  if (-not [string]::IsNullOrWhiteSpace($blockedReason)) {
+    $summary += ", blocked_reason=$blockedReason"
+  }
+
+  $targetDoc = "docs/harness/governance-auto-repair.md"
+  if ($failedStage -match "stage1|spec|design") {
+    $targetDoc = "docs/harness/rule-governance.md"
+  }
+  elseif ($failedStage -match "stage2|review|test|verify") {
+    $targetDoc = "docs/testing/failure-triage.md"
+  }
+
+  $hashInput = "$relativeTrace|$summary"
+  $bytes = [System.Text.Encoding]::UTF8.GetBytes($hashInput)
+  $sha = [System.Security.Cryptography.SHA256]::Create()
+  try {
+    $hash = ([System.BitConverter]::ToString($sha.ComputeHash($bytes))).Replace("-", "").Substring(0, 16).ToLowerInvariant()
+  }
+  finally {
+    $sha.Dispose()
+  }
+
+  return [pscustomobject]@{
+    hash = $hash
+    task_id = $taskId
+    status = $status
+    failed_stage = $failedStage
+    blocked_reason = $blockedReason
+    trace = $relativeTrace
+    summary = $summary
+    target_doc = $targetDoc
+  }
+}
+
+function Write-ExperienceEntry {
+  param(
+    [string]$Root,
+    [object]$Experience
+  )
+
+  if ($null -eq $Experience) {
+    return $false
+  }
+
+  $docPath = Join-Path $Root "docs\harness\governance-auto-repair.md"
+  $docDir = Split-Path -Parent $docPath
+  if (-not (Test-Path -LiteralPath $docDir)) {
+    New-Item -ItemType Directory -Force -Path $docDir | Out-Null
+  }
+
+  $marker = "<!-- stop-hook-experience:$($Experience.hash) -->"
+  if (Test-Path -LiteralPath $docPath) {
+    $existing = Get-Content -LiteralPath $docPath -Raw
+    if ($existing.Contains($marker)) {
+      return $false
+    }
+  }
+  else {
+    @"
+# Governance Auto Repair
+
+本文件由 Stop hook 治理检查维护，用于记录自动化闭环中反复出现的失败原因、修复去向和后续规则提升候选。这里不是硬规则入口；只有经过复验和维护者确认后，才可提升到 `AGENTS.md`、`.codex/rules/*.md`、prompt 或 `.rules`。
+
+"@ | Set-Content -LiteralPath $docPath -Encoding UTF8
+  }
+
+  $entry = @"
+
+## Stop Hook Experience - $($Experience.task_id)
+
+$marker
+
+- Time: $(Get-Date -Format o)
+- Summary: $($Experience.summary)
+- Trace: `$($Experience.trace)`
+- Suggested target doc: `$($Experience.target_doc)`
+- Next action: review the trace, repair the root cause, then promote only reusable lessons to the target doc.
+
+"@
+
+  Add-Content -LiteralPath $docPath -Value $entry -Encoding UTF8
+  return $true
+}
+
+try {
+  $resolvedRoot = (Resolve-Path -LiteralPath $ProjectRoot).Path
+  $findings = New-Object System.Collections.Generic.List[object]
+
+  Test-MergeMarkers -Root $resolvedRoot -Findings $findings
+  Test-HookSurface -Root $resolvedRoot -Findings $findings
+  Test-RulesSurface -Root $resolvedRoot -Findings $findings
+  Test-ConfigSurface -Root $resolvedRoot -Findings $findings
+
+  $experience = New-ExperienceFromTrace -Root $resolvedRoot
+  $experienceWritten = $false
+  if ($WriteExperience -and $null -ne $experience) {
+    $experienceWritten = Write-ExperienceEntry -Root $resolvedRoot -Experience $experience
+  }
+
+  if ($null -ne $experience) {
+    Add-Finding `
+      -Findings $findings `
+      -Severity "block" `
+      -Category "failed_trace_experience" `
+      -Message $experience.summary `
+      -RepairMode "agent_repair" `
+      -TargetDoc $experience.target_doc
+  }
+
+  $hasBlockingFinding = @($findings | Where-Object { $_.severity -eq "block" }).Count -gt 0
+  $status = if ($hasBlockingFinding) { "fail" } else { "pass" }
+
+  [pscustomobject]@{
+    status = $status
+    findings = @($findings.ToArray())
+    experience = $experience
+    experience_written = $experienceWritten
+    next_action = "Read AGENTS.md, docs/harness/governance-auto-repair.md, docs/harness/rule-governance.md, and .codex/rules/agents.md; use harness-writer for semantic repairs and rerun tools/harness/verify.ps1."
+  } | ConvertTo-Json -Depth 8 -Compress
+}
+catch {
+  $line = if ($null -ne $_.InvocationInfo) { [string]$_.InvocationInfo.ScriptLineNumber } else { "" }
+  [pscustomobject]@{
+    status = "fail"
+    findings = @([pscustomobject]@{
+      severity = "block"
+      category = "governance_check_error"
+      message = if ([string]::IsNullOrWhiteSpace($line)) { $_.Exception.Message } else { "$($_.Exception.Message) at line $line" }
+      repair_mode = "agent_repair"
+      target_doc = "docs/harness/governance-auto-repair.md"
+    })
+    experience = $null
+    experience_written = $false
+    next_action = "Inspect scripts/harness/harness-governance-check.ps1 and rerun tools/harness/verify.ps1."
+  } | ConvertTo-Json -Depth 8 -Compress
+}

package/package-source/docs/codex-harness-engineering/templates/spec/01-spec-guide-and-index.md

@@ -0,0 +1,32 @@
+# 01 Spec 写作总则与编号索引
+
+## 职责
+
+本文是项目 Spec 包的入口，规定 01-14 文档的职责、状态、编号和引用规则。
+
+## 文档索引
+
+| 编号 | 文件 | 阶段 | 职责 |
+| --- | --- | --- | --- |
+| 01 | `01-spec-guide-and-index.md` | Meta | 写作规则与索引 |
+| 02 | `02-requirement-sources.md` | Meta | 需求来源 |
+| 03 | `03-proposal-and-scope.md` | Proposal | 立项与范围 |
+| 04 | `04-prd.md` | Proposal | 产品需求 |
+| 05 | `05-user-stories-and-acceptance.md` | Spec | 用户故事与验收 |
+| 06 | `06-functional-spec.md` | Spec | 功能与交互规格 |
+| 07 | `07-nfr.md` | Spec | 非功能约束 |
+| 08 | `08-architecture-design.md` | Design | 架构设计 |
+| 09 | `09-api-contract.md` | Design | API 契约 |
+| 10 | `10-data-model.md` | Design | 数据模型 |
+| 11 | `11-security-design.md` | Design | 安全设计 |
+| 12 | `12-implementation-plan.md` | Plan | 实施计划 |
+| 13 | `13-test-strategy.md` | Test | 测试策略 |
+| 14 | `14-rtm.md` | Trace | 追踪矩阵 |
+
+## 规则
+
+- 行为变更先改 05，再同步 06、09、10、13、14。
+- 对外接口字段以 09 为准。
+- 数据字段以 10 为准。
+- 测试覆盖以 13 和 14 对账。
+- 本文不写业务需求正文。

package/package-source/docs/codex-harness-engineering/templates/spec/02-requirement-sources.md

@@ -0,0 +1,26 @@
+# 02 需求来源与采集记录
+
+## 职责
+
+记录需求的一手来源，包括会议、访谈、邮件、工单、截图和业务材料。本文只描述来源和原始语义，不直接承诺产品范围。
+
+## 来源清单
+
+| 来源 ID | 类型 | 日期 | 提供方 | 摘要 | 下游引用 |
+| --- | --- | --- | --- | --- | --- |
+| SRC-001 | meeting | YYYY-MM-DD | TBD | TBD | 03 / 04 |
+
+## 原始记录摘要
+
+### SRC-001
+
+- 背景：TBD
+- 原话或关键事实：TBD
+- 待澄清问题：TBD
+
+## 输出规则
+
+- 原始材料可以归档到 `docs/spec/archive/`，本文只保留可检索摘要。
+- 最终范围进入 03。
+- 产品规则进入 04。
+- 可验收行为进入 05。

package/package-source/docs/codex-harness-engineering/templates/spec/03-proposal-and-scope.md

@@ -0,0 +1,36 @@
+# 03 立项提案与范围说明
+
+## 职责
+
+说明为什么做、做什么、不做什么，以及当前阶段的成功标准。
+
+## 背景与问题
+
+- 背景：TBD
+- 当前问题：TBD
+- 目标用户或团队：TBD
+
+## Phase 边界
+
+| Phase | In Scope | Out of Scope |
+| --- | --- | --- |
+| Phase 1 | TBD | TBD |
+| Phase 2 | TBD | TBD |
+
+## 成功标准
+
+| 标准 ID | 描述 | 证据 |
+| --- | --- | --- |
+| SUCCESS-001 | TBD | TBD |
+
+## 风险
+
+| 风险 ID | 风险 | 缓解 |
+| --- | --- | --- |
+| RISK-001 | TBD | TBD |
+
+## 禁止混入
+
+- API 字段定义。
+- 数据库表结构。
+- 测试用例正文。

package/package-source/docs/codex-harness-engineering/templates/spec/04-prd.md

@@ -0,0 +1,29 @@
+# 04 产品需求说明 PRD
+
+## 职责
+
+用产品语言描述用户、场景、规则和能力优先级。本文不定义接口、表结构或实现方案。
+
+## 目标用户
+
+| 用户 ID | 用户类型 | 目标 | 痛点 |
+| --- | --- | --- | --- |
+| USER-001 | TBD | TBD | TBD |
+
+## 业务场景
+
+| 场景 ID | 场景 | 触发条件 | 预期结果 |
+| --- | --- | --- | --- |
+| SC-001 | TBD | TBD | TBD |
+
+## 产品规则
+
+| 规则 ID | 规则 | 优先级 | 下游引用 |
+| --- | --- | --- | --- |
+| RULE-001 | TBD | P0 | 05 / 13 / 14 |
+
+## 能力优先级
+
+| 能力 | 优先级 | Phase | 说明 |
+| --- | --- | --- | --- |
+| TBD | P0 | Phase 1 | TBD |