@pzy560117/codex-harness 0.1.3 → 0.1.4

package/package-source/docs/codex-harness-engineering/templates/testing/failure-triage.md

@@ -1,62 +1,62 @@
-# 失败归因
-
-## 一级分类
-
-先做五选一，不要一上来就改代码或改断言。
-
-| 一级分类 | 定义 | 允许动作 | 禁止动作 |
-| --- | --- | --- | --- |
-| `TEST_CODE_ISSUE` | 定位器、断言、等待时机、fixture 或测试搭建错误 | 修测试代码，保持原测试意图 | 弱化断言掩盖产品问题 |
-| `PRODUCT_BUG` | 实际行为违反需求、契约或设计预期 | 输出 bug report，按 owner 修业务代码 | 把 bug 改写成测试通过 |
-| `REQUIREMENT_CHANGE` | 规格、文案、流程或契约已明确变化 | 先更新真相源，再更新测试 | 不更新规格就改测试预期 |
-| `ENV_OR_DATA_ISSUE` | 服务未启动、数据不完整、权限、端口、外部依赖问题 | 修环境 / 数据并重跑 | 删除测试或直接跳过 |
-| `FLAKY` | 偶发、非确定性、重跑不稳定 | 收集证据，修等待/隔离/时序 | 用 `waitForTimeout` 掩盖问题 |
-
-## 二级归因
-
-在一级分类后，再细分 owner。
-
-| 失败类别 | 对应一级分类 | 典型信号 | 归属方 | 修复目标 | 回归执行方 |
-| --- | --- | --- | --- | --- | --- |
-| `REQ_GAP` | `REQUIREMENT_CHANGE` | 缺少验收示例、业务规则含糊、没有可观察判定依据 | 产品 | 产品 / 需求负责人 | 原审查人或测试代理 |
-| `TRACE_GAP` | `REQUIREMENT_CHANGE` | 需求未映射到 UI / API / 测试 / 证据 | requirements-trace | 追溯负责人 | 原审查人或测试代理 |
-| `DESIGN_GAP` | `REQUIREMENT_CHANGE` | 缺少状态、选择器、交互或视觉规则 | 设计 | 设计负责人 | 原视觉 / 测试代理 |
-| `CONTRACT_GAP` | `REQUIREMENT_CHANGE` | 缺字段、类型错误、错误码错误、鉴权规则不清楚 | 契约 | 契约负责人 | 契约测试者 |
-| `FRONTEND_BUG` | `PRODUCT_BUG` | 按钮不可点击、路由错误、状态缺失 | 前端 | 原开发者 | 原测试代理 |
-| `BACKEND_BUG` | `PRODUCT_BUG` | 500、业务规则错误、权限未生效 | 后端 | 后端开发者 | API 测试者 |
-| `TEST_BUG` | `TEST_CODE_ISSUE` | 断言错误、等待不稳定、fixture 无效或误报 | 测试 | 测试作者 | 原测试代理 |
-| `TEST_DATA_GAP` | `ENV_OR_DATA_ISSUE` | 缺少 seed、账号状态错误、数据重置不可靠 | 测试 / 数据 | 测试数据负责人 | E2E 测试者 |
-| `ENV_BUG` | `ENV_OR_DATA_ISSUE` | 端口冲突、服务未启动、依赖缺失 | 环境 | controller / 操作人 | test-runner |
-| `FLAKY` | `FLAKY` | 间歇性、非确定性失败 | test-runner | 对应 worker + 测试负责人 | 原测试代理 |
-| `SECURITY_RISK` | `PRODUCT_BUG` | 认证、权限、密钥或敏感数据问题 | 安全 | 安全 / 后端负责人 | 安全审查者 |
-
-## 归因记录模板
-
-```md
-### Finding ID
-
-- 一级分类:
-- 二级分类:
-- 失败测试 / 命令:
-- 责任方:
-- 根因:
-- 证据:
-  - 日志:
-  - trace:
-  - screenshot / video:
-  - network / console:
-- 修复动作:
-- 重新运行结果:
-- 后续验证:
-```
-
-## 规则
-
-- 不要默认把所有失败都归给前端。
-- 先从 `repo-map`、`verify-matrix`、`acceptance examples` 和相关测试计划确认预期，再判断失败性质。
-- 需求或追溯缺陷应回退给产品 / 追溯负责人，不应由实现者自行猜测修补。
-- 契约缺陷应先在契约或对应 owner 流程中修复；不要在前端 / 后端绕过问题。
-- 不要只靠代码评审就关闭 finding；应重跑最小相关测试。
-- 提出 finding 的测试者 / 审查者应在修复后负责关闭它。
-- 环境和网络失败除非超出重试预算并重复出现，否则不应视为产品失败。
-- `FLAKY` 不是兜底垃圾桶；必须附带重跑结果和时序 / 隔离分析。
+# 失败归因
+
+## 一级分类
+
+先做五选一，不要一上来就改代码或改断言。
+
+| 一级分类 | 定义 | 允许动作 | 禁止动作 |
+| --- | --- | --- | --- |
+| `TEST_CODE_ISSUE` | 定位器、断言、等待时机、fixture 或测试搭建错误 | 修测试代码，保持原测试意图 | 弱化断言掩盖产品问题 |
+| `PRODUCT_BUG` | 实际行为违反需求、契约或设计预期 | 输出 bug report，按 owner 修业务代码 | 把 bug 改写成测试通过 |
+| `REQUIREMENT_CHANGE` | 规格、文案、流程或契约已明确变化 | 先更新真相源，再更新测试 | 不更新规格就改测试预期 |
+| `ENV_OR_DATA_ISSUE` | 服务未启动、数据不完整、权限、端口、外部依赖问题 | 修环境 / 数据并重跑 | 删除测试或直接跳过 |
+| `FLAKY` | 偶发、非确定性、重跑不稳定 | 收集证据，修等待/隔离/时序 | 用 `waitForTimeout` 掩盖问题 |
+
+## 二级归因
+
+在一级分类后，再细分 owner。
+
+| 失败类别 | 对应一级分类 | 典型信号 | 归属方 | 修复目标 | 回归执行方 |
+| --- | --- | --- | --- | --- | --- |
+| `REQ_GAP` | `REQUIREMENT_CHANGE` | 缺少验收示例、业务规则含糊、没有可观察判定依据 | 产品 | 产品 / 需求负责人 | 原审查人或测试代理 |
+| `TRACE_GAP` | `REQUIREMENT_CHANGE` | 需求未映射到 UI / API / 测试 / 证据 | requirements-trace | 追溯负责人 | 原审查人或测试代理 |
+| `DESIGN_GAP` | `REQUIREMENT_CHANGE` | 缺少状态、选择器、交互或视觉规则 | 设计 | 设计负责人 | 原视觉 / 测试代理 |
+| `CONTRACT_GAP` | `REQUIREMENT_CHANGE` | 缺字段、类型错误、错误码错误、鉴权规则不清楚 | 契约 | 契约负责人 | 契约测试者 |
+| `FRONTEND_BUG` | `PRODUCT_BUG` | 按钮不可点击、路由错误、状态缺失 | 前端 | 原开发者 | 原测试代理 |
+| `BACKEND_BUG` | `PRODUCT_BUG` | 500、业务规则错误、权限未生效 | 后端 | 后端开发者 | API 测试者 |
+| `TEST_BUG` | `TEST_CODE_ISSUE` | 断言错误、等待不稳定、fixture 无效或误报 | 测试 | 测试作者 | 原测试代理 |
+| `TEST_DATA_GAP` | `ENV_OR_DATA_ISSUE` | 缺少 seed、账号状态错误、数据重置不可靠 | 测试 / 数据 | 测试数据负责人 | E2E 测试者 |
+| `ENV_BUG` | `ENV_OR_DATA_ISSUE` | 端口冲突、服务未启动、依赖缺失 | 环境 | controller / 操作人 | test-runner |
+| `FLAKY` | `FLAKY` | 间歇性、非确定性失败 | test-runner | 对应 worker + 测试负责人 | 原测试代理 |
+| `SECURITY_RISK` | `PRODUCT_BUG` | 认证、权限、密钥或敏感数据问题 | 安全 | 安全 / 后端负责人 | 安全审查者 |
+
+## 归因记录模板
+
+```md
+### Finding ID
+
+- 一级分类:
+- 二级分类:
+- 失败测试 / 命令:
+- 责任方:
+- 根因:
+- 证据:
+  - 日志:
+  - trace:
+  - screenshot / video:
+  - network / console:
+- 修复动作:
+- 重新运行结果:
+- 后续验证:
+```
+
+## 规则
+
+- 不要默认把所有失败都归给前端。
+- 先从 `repo-map`、`verify-matrix`、`acceptance examples` 和相关测试计划确认预期，再判断失败性质。
+- 需求或追溯缺陷应回退给产品 / 追溯负责人，不应由实现者自行猜测修补。
+- 契约缺陷应先在契约或对应 owner 流程中修复；不要在前端 / 后端绕过问题。
+- 不要只靠代码评审就关闭 finding；应重跑最小相关测试。
+- 提出 finding 的测试者 / 审查者应在修复后负责关闭它。
+- 环境和网络失败除非超出重试预算并重复出现，否则不应视为产品失败。
+- `FLAKY` 不是兜底垃圾桶；必须附带重跑结果和时序 / 隔离分析。

package/package-source/docs/codex-harness-engineering/templates/testing/test-data-plan.md

@@ -1,36 +1,36 @@
-# 测试数据计划
-
-**功能**:
-**Seed 负责人**:
-**重置命令**:
-**Seed 命令**:
-
-## 1. 账号
-
-| 角色 | 用户名 / 邮箱 | 权限 | 用途 |
-| --- | --- | --- | --- |
-| guest | N/A | 匿名 | 浏览 |
-| user | | 标准用户 | 核心流程 |
-| admin | | 管理员 | 管理流程 |
-
-## 2. 领域数据
-
-| Data ID | 类型 | 状态 | 用途 |
-| --- | --- | --- | --- |
-| seed-normal-001 | | 正常 | 正常路径 |
-| seed-empty-001 | | 空 | 空状态 |
-| seed-error-001 | | 无效 / 错误 | 错误路径 |
-
-## 3. 边界情况
-
-- 空数据:
-- 长文本:
-- 无效值:
-- 权限拒绝:
-- 网络 / API 错误:
-
-## 4. 重置规则
-
-- 测试必须可重复执行。
-- E2E 不得依赖手工准备的本地数据。
-- 破坏性测试必须重置或隔离其数据。
+# 测试数据计划
+
+**功能**:
+**Seed 负责人**:
+**重置命令**:
+**Seed 命令**:
+
+## 1. 账号
+
+| 角色 | 用户名 / 邮箱 | 权限 | 用途 |
+| --- | --- | --- | --- |
+| guest | N/A | 匿名 | 浏览 |
+| user | | 标准用户 | 核心流程 |
+| admin | | 管理员 | 管理流程 |
+
+## 2. 领域数据
+
+| Data ID | 类型 | 状态 | 用途 |
+| --- | --- | --- | --- |
+| seed-normal-001 | | 正常 | 正常路径 |
+| seed-empty-001 | | 空 | 空状态 |
+| seed-error-001 | | 无效 / 错误 | 错误路径 |
+
+## 3. 边界情况
+
+- 空数据:
+- 长文本:
+- 无效值:
+- 权限拒绝:
+- 网络 / API 错误:
+
+## 4. 重置规则
+
+- 测试必须可重复执行。
+- E2E 不得依赖手工准备的本地数据。
+- 破坏性测试必须重置或隔离其数据。

package/package-source/docs/codex-harness-engineering/templates/testing/test-report.md

@@ -1,41 +1,85 @@
-# 测试报告
-
-**会话**:
-**代理**:
-**结论**: PASS / FAIL / BLOCKED
-**开始时间**:
-**结束时间**:
-
-## 环境
-
-- 前端:
-- 后端:
-- 分支:
-- Seed:
-
-## 摘要
-
-| 测试区域 | 总计 | PASS | FAIL | BLOCKED | 证据 |
-| --- | --- | --- | --- | --- | --- |
-| 单元 | | | | | |
-| 组件 | | | | | |
-| 契约 | | | | | |
-| API 集成 | | | | | |
-| E2E | | | | | |
-| 视觉 | | | | | |
-
-## Findings
-
-| Finding ID | 严重程度 | 失败类别 | 责任方提示 | 证据 | 状态 |
-| --- | --- | --- | --- | --- | --- |
-| | | | | | |
-
-## 返回给 Controller
-
-```text
-Verdict:
-Report:
-Findings:
-Needs repair:
-Owner hints:
-```
+# 测试报告
+
+**会话**:
+**代理**:
+**结论**: PASS / FAIL / BLOCKED
+**开始时间**:
+**结束时间**:
+
+## 环境
+
+- 前端:
+- 后端:
+- 分支:
+- Seed:
+
+## 需求完成情况
+
+| Requirement / AC | 状态 | 对应文件 / 证据 | 备注 |
+| --- | --- | --- | --- |
+| | pass / fail / partial / blocked | | |
+
+## 修改文件清单
+
+| 文件 | 变更类型 | 说明 |
+| --- | --- | --- |
+| | create / update / delete | |
+
+## 核心实现说明
+
+- 复用内容:
+- 新增内容:
+- 为什么这样实现:
+
+## 影响范围
+
+- 直接影响:
+- 间接影响:
+- 相关接口 / 页面 / 配置:
+
+## 摘要
+
+| 测试区域 | 总计 | PASS | FAIL | BLOCKED | 证据 |
+| --- | --- | --- | --- | --- | --- |
+| 单元 | | | | | |
+| 组件 | | | | | |
+| 契约 | | | | | |
+| API 集成 | | | | | |
+| E2E | | | | | |
+| 视觉 | | | | | |
+
+## Findings
+
+| Finding ID | 严重程度 | 失败类别 | 责任方提示 | 证据 | 状态 |
+| --- | --- | --- | --- | --- | --- |
+| | | | | | |
+
+## 未测试内容
+
+- 未运行测试:
+- 原因:
+
+## 已知风险
+
+- 风险:
+- 缓解措施:
+
+## 回滚方式
+
+- 代码回滚:
+- 配置 / 数据回滚:
+
+## 逐条对照需求
+
+- Requirement / AC 1:
+- Requirement / AC 2:
+
+## 返回给 Controller
+
+```text
+Verdict:
+Report:
+Findings:
+Needs repair:
+Owner hints:
+```

package/package-source/docs/codex-harness-engineering/templates/testing/verify-matrix.md

@@ -17,17 +17,27 @@
 | 契约 | | API / 数据变更时必需 | | |
 | API 集成 | | 后端变更时必需 | | |
 | Oracle 审查 | `TEST_STRATEGY.md` + `test-matrix.md` | P0/P1 / 高风险必需 | | |
-| 副作用断言 | DB diff / cache / event / audit / file evidence | 写操作、状态流转、异步必需 | | |
-| 权限无副作用 | denied response + unchanged data + no leak | 权限 / 多租户必需 | | |
-| 假测试检测 | Stage 2 review | 测试改动时必需 | | |
+| 副作用断言 | DB diff / cache / event / audit / file evidence | 写操作、状态流转、异步必需 | | |
+| 状态唯一来源检查 | `frontend-architecture.md` 状态表 + CURRENT_TASK 状态决策 | UI / 表单 / 查询状态变更时必需 | | |
+| 缓存失效检查 | cache key / invalidate 证据 / refetch 结果 | 远程数据、列表、详情、统计变更时必需 | | |
+| 权限无副作用 | denied response + unchanged data + no leak | 权限 / 多租户必需 | | |
+| 输入校验检查 | schema / validator + invalid payload response | API / 表单 / 文件上传时必需 | | |
+| 敏感信息脱敏检查 | response/log/trace redaction evidence | 涉及账号、支付、PII、密钥时必需 | | |
+| 风控 / 限流检查 | rate limit / captcha / idempotency evidence | 登录、注册、验证码、支付、上传等高风险入口必需 | | |
+| 平台差异检查 | iOS / Android / H5 差异记录 + 对应证据 | 移动端 / WebView / 小程序必需 | | |
+| 权限弹窗 / 拒绝回退 | 系统权限申请、拒绝、再次授权路径证据 | 相机、相册、定位、通知等权限场景必需 | | |
+| 生命周期 / 中断恢复 | 切后台、切前台、支付中断、网络恢复、登录过期证据 | 移动端主流程必需 | | |
+| 真机 / 版本矩阵 | 设备型号、系统版本、低端机或弱网验证 | 移动端 / H5 发布前必需 | | |
+| 假测试检测 | Stage 2 review | 测试改动时必需 | | |
 | 受影响测试 | changed-code-related tests | 业务逻辑变更时必需 | | |
 | 用户验收链路 | story entry + action + business Oracle + side effect / no-side-effect evidence | feature_impl 完成前必需 | | |
 | E2E | | P0/P1 主流程变更时必需 | | |
 | P0 回归 | 核心 P0 场景 | 发布前必需 | | |
 | 发布候选验证 | cross-story flow + P0/P1 regression + contract/API + E2E/visual as applicable | release 完成前必需 | | |
 | 失败态验收 | negative path / denied path / invalid state / downstream failure evidence | P0/P1 / 高风险必需 | | |
-| 视觉一致性 | `visual-parity-review.md` | UI 变更时必需 | | |
-| 覆盖率 | `coverage-summary.json` | 如策略适用 | | |
+| 视觉一致性 | `visual-parity-review.md` | UI 变更时必需 | | |
+| 覆盖率 | `coverage-summary.json` | 如策略适用 | | |
+| 交付验收报告 | `test-report.md` / 发布说明 / 需求逐条对照 | feature_impl / release 完成前必需 | | |
 | PKG-LAYER-P5-MIGRATE-APPLY 自然语言用例 | `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md` 中 `TC-PKG-LAYER-P5-APPLY-001..006` | P1 必需 | planned | `traces/`, `tools/harness/tests/test-install-modes.ps1` |
 | PKG-LAYER-P5-MIGRATE-APPLY TDD RED/GREEN/REFACTOR | `tools/harness/tests/test-install-modes.ps1` 先补迁移执行失败断言，再实现通过 | P1 必需 | planned | `traces/` |
 | PKG-LAYER-P5-MIGRATE-APPLY 验收链路 | clean legacy full、drift、unknown、missing vendor、manual-review、thin no-op smoke | P1 必需 | planned | `traces/`, doctor 输出, refresh CheckOnly 输出 |

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

@@ -0,0 +1,14 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放会复制到项目 `tools/harness/` 的内容级门禁脚本模板。
+
+## 结构索引
+
+- `harness/*.ps1`：spec、context、session、architecture、testing、impact，以及 recommended / high-risk 门禁脚本。
+
+## 修改规则
+
+- 这里的脚本属于 canonical，改动后通常要同步当前仓库活跃副本 `tools/harness/`。
+- 不要只改脚本文案；涉及门禁语义变化时，要同步 `task-session-strategy.md`、使用文档和任务模板默认值。

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

@@ -0,0 +1,37 @@
+param(
+  [string]$ProjectRoot = "",
+  [switch]$AsJson,
+  [switch]$AllowWarningsOnly
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+if ([string]::IsNullOrWhiteSpace($ProjectRoot)) {
+  $ProjectRoot = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot "..\..\..\.."))
+}
+
+function New-Issue { param([string]$Severity,[string]$File,[string]$Section,[string]$Message) [PSCustomObject]@{ severity=$Severity; file=$File; section=$Section; message=$Message } }
+function Get-FileContentOrNull { param([string]$Path) if (-not (Test-Path -LiteralPath $Path)) { return $null }; Get-Content -LiteralPath $Path -Raw }
+function Test-ContainsAll { param([string]$Content,[string[]]$Terms) foreach ($term in $Terms) { if ($Content -notmatch [regex]::Escape($term)) { return $false } }; return $true }
+
+$issues = @()
+$testReport = Get-FileContentOrNull (Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\testing\test-report.md")
+$currentTask = Get-FileContentOrNull (Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\context\CURRENT_TASK.md")
+$verifyMatrix = Get-FileContentOrNull (Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\testing\verify-matrix.md")
+
+if ($null -eq $testReport) { $issues += New-Issue "error" "docs/codex-harness-engineering/templates/testing/test-report.md" "file" "缺少 test-report 模板。" }
+elseif (-not (Test-ContainsAll $testReport @("需求完成情况", "修改文件清单", "核心实现说明", "影响范围", "未测试内容", "已知风险", "回滚方式", "逐条对照需求"))) { $issues += New-Issue "error" "docs/codex-harness-engineering/templates/testing/test-report.md" "acceptance-report" "test-report 模板缺少第24章要求的验收报告字段。" }
+if ($null -eq $currentTask) { $issues += New-Issue "warning" "docs/codex-harness-engineering/templates/context/CURRENT_TASK.md" "file" "缺少 CURRENT_TASK 模板。" }
+elseif (-not (Test-ContainsAll $currentTask @("交付验收报告路径", "逐条需求完成情况"))) { $issues += New-Issue "warning" "docs/codex-harness-engineering/templates/context/CURRENT_TASK.md" "acceptance-fields" "CURRENT_TASK 模板缺少第24章要求的交付报告追踪字段。" }
+if ($null -eq $verifyMatrix) { $issues += New-Issue "warning" "docs/codex-harness-engineering/templates/testing/verify-matrix.md" "file" "缺少 verify-matrix 模板。" }
+elseif (-not (Test-ContainsAll $verifyMatrix @("交付验收报告", "用户验收链路", "失败态验收"))) { $issues += New-Issue "warning" "docs/codex-harness-engineering/templates/testing/verify-matrix.md" "delivery-verification" "verify-matrix 模板缺少第24章要求的交付验收闭环。" }
+
+$errors = @($issues | Where-Object severity -eq "error")
+$warnings = @($issues | Where-Object severity -eq "warning")
+$exitCode = if ($errors.Count -gt 0) { 1 } elseif ($warnings.Count -gt 0 -and -not $AllowWarningsOnly) { 2 } else { 0 }
+if ($AsJson) { [PSCustomObject]@{ ok = ($exitCode -eq 0); errors = $errors; warnings = $warnings } | ConvertTo-Json -Depth 6; exit $exitCode }
+if ($errors.Count -eq 0 -and $warnings.Count -eq 0) { Write-Output "Acceptance lint passed."; exit 0 }
+if ($errors.Count -gt 0) { Write-Output "Acceptance lint failed."; foreach ($issue in $errors) { Write-Output ("- [ERROR] {0} :: {1} :: {2}" -f $issue.file, $issue.section, $issue.message) } }
+if ($warnings.Count -gt 0) { if ($errors.Count -eq 0) { Write-Output "Acceptance lint passed with warnings." }; foreach ($issue in $warnings) { Write-Output ("- [WARNING] {0} :: {1} :: {2}" -f $issue.file, $issue.section, $issue.message) } }
+exit $exitCode

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

@@ -0,0 +1,150 @@
+param(
+  [string]$ProjectRoot = "",
+  [switch]$AsJson,
+  [switch]$AllowWarningsOnly
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+if ([string]::IsNullOrWhiteSpace($ProjectRoot)) {
+  $ProjectRoot = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot "..\.."))
+}
+
+function New-Issue {
+  param(
+    [string]$Severity,
+    [string]$File,
+    [string]$Section,
+    [string]$Message
+  )
+
+  [PSCustomObject]@{
+    severity = $Severity
+    file = $File
+    section = $Section
+    message = $Message
+  }
+}
+
+function Get-FileContentOrNull {
+  param([string]$Path)
+
+  if (-not (Test-Path -LiteralPath $Path)) {
+    return $null
+  }
+
+  Get-Content -LiteralPath $Path -Raw
+}
+
+function Test-ContainsPlaceholder {
+  param([string]$Content)
+
+  if ([string]::IsNullOrWhiteSpace($Content)) {
+    return $false
+  }
+
+  return (
+    $Content -match '(?im)\bTBD\b' -or
+    $Content -match '(?im)\bTODO\b' -or
+    $Content -match '(?im)<replace-' -or
+    $Content -match '(?im)REQ-REPLACE|FR-REPLACE|NFR-REPLACE|META-HANDOFF-REPLACE'
+  )
+}
+
+function Test-ContainsAll {
+  param(
+    [string]$Content,
+    [string[]]$Terms
+  )
+
+  foreach ($term in $Terms) {
+    if ($Content -notmatch [regex]::Escape($term)) {
+      return $false
+    }
+  }
+
+  return $true
+}
+
+$issues = @()
+
+$architectureRulesPath = Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\docs\project-agents-template.md"
+$currentTaskPath = Join-Path $ProjectRoot "docs\codex-harness-engineering\templates\context\CURRENT_TASK.md"
+$taskTemplatePath = Join-Path $ProjectRoot "tools\harness\templates\project-task-template.json"
+
+$architectureRules = Get-FileContentOrNull -Path $architectureRulesPath
+$currentTask = Get-FileContentOrNull -Path $currentTaskPath
+$taskTemplate = Get-FileContentOrNull -Path $taskTemplatePath
+
+if ($null -eq $architectureRules) {
+  $issues += New-Issue -Severity "error" -File "docs/codex-harness-engineering/templates/docs/project-agents-template.md" -Section "file" -Message "缺少 project AGENTS 模板，无法承载第三章目录级架构规则。"
+}
+else {
+  if (-not (Test-ContainsAll -Content $architectureRules -Terms @("全项目都成立的入口规则", "子目录", "本目录负责什么", "本目录不负责什么", "决策表"))) {
+    $issues += New-Issue -Severity "error" -File "docs/codex-harness-engineering/templates/docs/project-agents-template.md" -Section "local-agents-architecture" -Message "project AGENTS 模板缺少目录级架构规则承载结构。"
+  }
+  if (-not (Test-ContainsAll -Content $architectureRules -Terms @("repository/service", "不要跨层调用"))) {
+    $issues += New-Issue -Severity "warning" -File "docs/codex-harness-engineering/templates/docs/project-agents-template.md" -Section "layering-sample" -Message "project AGENTS 模板还缺少更具体的分层规则样板。"
+  }
+}
+
+if ($null -eq $currentTask) {
+  $issues += New-Issue -Severity "error" -File "docs/codex-harness-engineering/templates/context/CURRENT_TASK.md" -Section "file" -Message "缺少 CURRENT_TASK 模板，无法承载第三章复用检查和模块归属。"
+}
+else {
+  if (-not (Test-ContainsAll -Content $currentTask -Terms @("这个功能属于哪个模块", "项目里有没有类似实现", "需要改哪些文件", "可能影响哪些调用方", "需要跑哪些测试"))) {
+    $issues += New-Issue -Severity "error" -File "docs/codex-harness-engineering/templates/context/CURRENT_TASK.md" -Section "reuse-check-fields" -Message "CURRENT_TASK 模板缺少第三章要求的模块归属和类似实现检查字段。"
+  }
+}
+
+if ($null -eq $taskTemplate) {
+  $issues += New-Issue -Severity "error" -File "tools/harness/templates/project-task-template.json" -Section "file" -Message "缺少 project-task-template，无法承载第三章计划约束。"
+}
+else {
+  if (Test-ContainsPlaceholder -Content $taskTemplate) {
+    $issues += New-Issue -Severity "warning" -File "tools/harness/templates/project-task-template.json" -Section "placeholders" -Message "task 模板仍包含占位符；这是模板预期，但需要保证第三章字段存在。"
+  }
+  if (-not (Test-ContainsAll -Content $taskTemplate -Terms @("architecture_constraints", "forbidden_implementations", "关键调用链", "受影响文件", "受影响测试"))) {
+    $issues += New-Issue -Severity "error" -File "tools/harness/templates/project-task-template.json" -Section "architecture-fields" -Message "task 模板缺少第三章所需的架构与影响面字段。"
+  }
+  if (-not (Test-ContainsAll -Content $taskTemplate -Terms @("模块归属", "文件改动清单", "复用内容", "新增内容", "不改内容", "风险点", "测试范围"))) {
+    $issues += New-Issue -Severity "error" -File "tools/harness/templates/project-task-template.json" -Section "design-plan-fields" -Message "task 模板缺少复杂功能技术方案字段。"
+  }
+}
+
+$errors = @($issues | Where-Object { $_.severity -eq "error" })
+$warnings = @($issues | Where-Object { $_.severity -eq "warning" })
+$exitCode = if ($errors.Count -gt 0) { 1 } elseif ($warnings.Count -gt 0 -and -not $AllowWarningsOnly) { 2 } else { 0 }
+
+if ($AsJson) {
+  [PSCustomObject]@{
+    ok = ($exitCode -eq 0)
+    errors = $errors
+    warnings = $warnings
+  } | ConvertTo-Json -Depth 6
+  exit $exitCode
+}
+
+if ($errors.Count -eq 0 -and $warnings.Count -eq 0) {
+  Write-Output "Architecture lint passed."
+  exit 0
+}
+
+if ($errors.Count -gt 0) {
+  Write-Output "Architecture lint failed."
+  foreach ($issue in $errors) {
+    Write-Output ("- [ERROR] {0} :: {1} :: {2}" -f $issue.file, $issue.section, $issue.message)
+  }
+}
+
+if ($warnings.Count -gt 0) {
+  if ($errors.Count -eq 0) {
+    Write-Output "Architecture lint passed with warnings."
+  }
+  foreach ($issue in $warnings) {
+    Write-Output ("- [WARNING] {0} :: {1} :: {2}" -f $issue.file, $issue.section, $issue.message)
+  }
+}
+
+exit $exitCode