@pzy560117/codex-harness 0.1.7 → 0.1.9

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.9
 ```
 
 适合 release smoke 或回滚到某个已发布版本。

package/package-source/AGENTS.md

@@ -7,6 +7,20 @@
 - 当前仓库根目录下的活跃文档或脚本，只在它本身就是 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 规则
+
+- 新增业务目录、模块职责变化、目录入口变化、目录级测试命令变化时，必须检查并更新最接近该目录的子目录 `AGENTS.md`。
+- 目录级 `AGENTS.md` 负责承载局部职责、边界、入口、测试命令、复用模式、坑点和禁止事项；不要把这类规则长期堆在根 `AGENTS.md`。
+- 自动托管区块 `AUTO-MODULE-FACTS` 只补动态事实，不等于目录规则完整；即使 facts 已自动刷新，仍需要有人维护手写的局部规则部分。
+- 如果 `task.json.owned_paths`、`docs/ai/repo-map.md` 或模块边界已经明确某目录是独立模块，而该目录缺少子目录 `AGENTS.md`，应视为至少 `warn`，高风险目录应直接阻断进入正式任务队列或实现阶段。
+
 ## 目录级规则
 
 - 当某个目录满足以下任一条件时，应优先考虑新增或更新该目录下的 `AGENTS.md`，而不是继续扩充根入口：
@@ -25,7 +39,10 @@
 
 ## 必读索引
 
-如果当前仓库是 thin install 项目，而下面列出的 `docs/harness/*` 或 `docs/knowledge/*` 不在项目根，先读取 `.codex-harness/state/config.json`，再到其中 `packageRoot` 下查同路径文件。
+如果当前仓库是 thin install 项目，而下面列出的 `docs/harness/*`、`docs/testing/*` 或 `docs/knowledge/*` 不在项目根，先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：
+- `docs/harness/*` -> `docs/codex-harness-engineering/templates/docs/*`
+- `docs/testing/*` -> `docs/codex-harness-engineering/templates/testing/*`
+- `docs/knowledge/*` -> `docs/codex-harness-engineering/templates/knowledge/*`
 
 - Harness 分层分析索引：`harness-analysis/README.md`
 - Codex Harness Engineering 总览：`docs/codex-harness-engineering/README.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/config/rules/agents.md

@@ -34,11 +34,11 @@ trigger: always_on
 | `contract-designer` | OpenAPI、mock、client 生成、字段和错误码契约 | `api-contract-template`, `api-design` | Contract First |
 | `backend-worker` | API、数据库、权限、异常流、后端测试 | `backend-patterns`, `database`, 项目后端技能 | 后端实现 |
 | `integration-worker` | 前后端联调、mock 切真实服务、主流程 E2E | `api-integration`, `fullstack-workflow` | Integration |
-| `test-planner` | 从需求阶段开始定义可测试需求、验收示例、追溯矩阵、测试数据、分层测试计划和证据路径 | `qa-e2e-planner`, `test-coverage`, `tdd` | 测试设计与测试左移 |
+| `test-planner` | 从需求阶段开始定义可测试需求、验收示例、追溯矩阵、测试数据、分层测试计划、影响面和证据路径；高风险用户可见任务要明确是否需要 `e2e-plan.md` | `qa-e2e-planner`, `test-coverage`, `tdd` | 测试设计与测试左移 |
 | `test-runner` | 运行确定性验证、汇总失败、写测试报告 | `e2e-runner`, `qa-e2e-runner`, `verify` | Verify / Regression |
 | `stage1-reviewer` | 产品、设计、计划一致性审查 | `spec-based-review`, `spec-review` | Stage 1 Review |
 | `stage2-reviewer` | 代码质量、测试覆盖、回归风险审查 | `code-reviewer`, `security-reviewer` | Stage 2 Review |
-| `failure-triage` | 失败归因、owner 分类、Repair Queue | `build-error-resolver`, `failure-triage.md` | 测试、构建、视觉或 review 失败后 |
+| `failure-triage` | 失败一级分类、owner 二级分类、Repair Queue | `build-error-resolver`, `failure-triage.md` | 测试、构建、视觉或 review 失败后 |
 | `repair-worker` | 按 finding 定点修复并复验 | 原开发 agent + `repair-one-finding.md` | 修复闭环 |
 | `docs-worker` | 文档、索引、使用指南、模板同步 | `doc-updater`, `update-docs` | 文档更新和交付归档 |
 | `security-reviewer` | 权限、认证、支付、密钥、敏感数据和 sandbox 风险 | `security-reviewer`, `security-review` | 高风险功能 |
@@ -86,7 +86,7 @@ trigger: always_on
 
 ## 子代理前置读取规则
 
-- 任何只读辅助子代理或 writer 子代理在开始判断前，必须先读 `AGENTS.md`、`docs/harness/task-session-strategy.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件）和本文件。
+- 任何只读辅助子代理或 writer 子代理在开始判断前，必须先读 `AGENTS.md`、`docs/harness/task-session-strategy.md`（thin project 缺失时先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：`docs/harness/* -> docs/codex-harness-engineering/templates/docs/*`、`docs/testing/* -> docs/codex-harness-engineering/templates/testing/*`、`docs/knowledge/* -> docs/codex-harness-engineering/templates/knowledge/*`）和本文件。
 - 子代理必须再读取该角色对应的 `.agents/skills/*/SKILL.md`（如存在）、项目 truth source 和必要的深文档，再输出结论。
 - 如果当前轮次是被 stop hook / continuation gate 强制继续后的续跑，先重新阅读上面这些文档，再决定是否真的需要子代理。
 - 只读辅助子代理默认只读，不直接写业务代码，不修改 `task.json`、`progress.txt`、`traces/`。

package/package-source/docs/codex-harness-engineering/templates/docs/project-agents-template.md

@@ -8,6 +8,7 @@
 - 只写会改变 Agent 行为的项目特定信息；通用工程常识、formatter/linter 已覆盖的内容不要写。
 - 根 `AGENTS.md` 保持短入口，建议 60-120 行；细节放到 `docs/`、`rules/`、`specs/` 或测试文档，并在入口索引引用。
 - 根 `AGENTS.md` 只写全项目都成立的入口规则；目录独有的模块职责、边界、入口、测试命令、坑点和禁止事项，优先写进最接近该目录的子目录 `AGENTS.md`。
+- 新增业务目录、模块职责变化、目录入口变化、目录级测试命令变化时，必须检查并更新最接近该目录的子目录 `AGENTS.md`；不要等 review 发现目录规则缺口后再补。
 - 如果项目同时维护模板源、镜像和运行时副本，先确认哪一份是 canonical；默认优先修改模板 canonical，再同步活跃副本，不要只修当前工作区现状。
 - 每条禁令必须给替代方案；不能说明替代方案的内容先写成风险或待确认项。
 - 可以自动检查的规则优先进入 lint、schema、hook、CI、verify 脚本，不只依赖文字提醒。
@@ -29,6 +30,7 @@
 | 测试入口 | test scripts、`tests/`、Playwright/Cypress/Pytest/Vitest 配置 |
 | 自动化检查 | linter、formatter、typecheck、CI、hooks |
 | 命名与业务词典 | `docs/harness/code-style-and-naming.md`、`docs/code-style.md`、接口 / 数据字典 |
+| 目录级规则覆盖 | `owned_paths`、`docs/ai/repo-map.md`、现有子目录 `AGENTS.md`、模块入口文件 |
 | 私域知识 | 内部组件库、私有 API、特殊目录、历史迁移约束 |
 | Bad Case | 近期 review、bug 标签、trace、失败复盘、团队反复纠正事项 |
 
@@ -57,6 +59,7 @@
 - 真实入口：<启动、构建、测试、driver 或任务系统入口>
 - 代码地图：`<docs/ai/repo-map.md 或同类导航文件>`；需要理解模块位置时先读它，再进入具体目录。
 - 如果存在目录级 `AGENTS.md`：进入对应目录后同时遵守根规则和本地规则。
+- 新增业务目录、模块职责变化、目录入口变化、目录级测试命令变化时，必须同步更新对应子目录 `AGENTS.md`。
 - 不要把 README 的业务介绍复制到这里；README 回答“项目是什么”，本文件回答“Agent 怎么改”。
 
 ## 模板与 Canonical
@@ -143,7 +146,7 @@
 
 ## 子目录 AGENTS.md 模板
 
-只有 monorepo 或目录规则明显不同时才添加子目录 `AGENTS.md`。子目录规则应比根规则更具体。
+只有 monorepo 或目录规则明显不同时才添加子目录 `AGENTS.md`。一旦目录已具备独立模块职责、入口、测试命令或反复出现局部坑点，就不应继续把规则堆在根入口文件里。
 
 ````markdown
 # <path> AGENTS.md
@@ -152,6 +155,7 @@
 
 - 本文件只适用于 `<path>/` 下的改动。
 - 根 `AGENTS.md` 仍然有效；本文件只补充或收紧本目录规则。
+- 如果存在 `<!-- BEGIN AUTO-MODULE-FACTS -->` 托管区块，它只维护动态事实；手写规则必须保留在托管区块外。
 
 ## 本目录约束
 
@@ -162,6 +166,7 @@
 - 修改前必须先看：<核心文件 / 规则 / 测试>
 - 测试命令：<目录级验证命令>
 - 常见复用对象：<组件 / hook / service / helper / fixture>
+- 常见坑和禁止事项：<本目录专属坑点，以及对应替代方案>
 
 ## 决策表
 
@@ -204,6 +209,8 @@
 | 是否包含通用编码常识 | 删除 |
 | 是否缺少代码地图入口 | 新增 `docs/ai/repo-map.md` 或说明为什么项目太小不需要 |
 | 是否把目录级规则堆在根 AGENTS.md | 下沉到最接近适用范围的子目录 `AGENTS.md` |
+| 是否新增了独立模块目录却没有子目录 `AGENTS.md` | 立即补齐，至少写职责、边界、入口、测试命令和局部禁止事项 |
+| 子目录 `AGENTS.md` 是否只剩 `AUTO-MODULE-FACTS` 托管区块 | 补手写规则，不要把动态 facts 当成目录规则完成态 |
 | 是否没有说明 canonical | 补充模板源 / 活跃副本 / 运行时副本的优先级 |
 | 禁令是否没有替代方案 | 补替代方案或降级为风险 |
 | 是否引用不存在的命令或路径 | 修正或删除 |

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

@@ -26,12 +26,18 @@
 - 标准交接入口是 `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`。
+- 创建或重建任务队列时，必须根据 `owned_paths`、`docs/ai/repo-map.md` 和模块职责判断哪些目录需要局部规则；命中独立模块目录却缺少子目录 `AGENTS.md` 时，不得把该任务队列视为正式完成。
 - 任务进入 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`。不得创建“先跑起来、后面再补测试/证据/整链路”的实现任务。
+- 自动刷新出来的 `AUTO-MODULE-FACTS` 只能证明目录事实被收集，不代表目录级规则完整；如果模块目录只有托管 facts 而没有职责、边界、入口、测试或禁止事项等手写规则，应继续标记为待补齐，而不是当作完成态。
 - 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 可见结果时，链路验证和失败验证不能省略。
@@ -121,6 +127,7 @@
 - 先收敛 truth source，再进入实现。
 - 大任务先拆成多个 `single` 任务，再交给 driver 顺序执行。
 - 当主控遇到文档、规则、任务队列、前端、后端或测试相关写入时，分别委派 `docs-worker`、`harness-writer`、`frontend-worker`、`backend-worker`、`test-runner` 等 writer 角色处理。
+- 目录级规则变化优先落到最接近该目录的子目录 `AGENTS.md`；根 `AGENTS.md` 只保留全局入口规则。
 - 实现阶段可以使用子代理并行加速，但必须按 owned paths 或明确文件组拆分；如需并行写入，不允许多个角色同时写同一路径。
 - 每个 writer 子代理启动前必须声明允许修改、禁止修改、验收输出和验证命令；只读子代理只能返回结构化结论。
 - 子代理不得修改 `task.json`、`progress.txt`、`traces/` 或 Git 状态；主实现会话必须整合子代理输出并运行当前任务 `test_command`。

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/package-assets/docs/codex-harness-engineering/project-agents-template.md

@@ -8,6 +8,7 @@
 - 只写会改变 Agent 行为的项目特定信息；通用工程常识、formatter/linter 已覆盖的内容不要写。
 - 根 `AGENTS.md` 保持短入口，建议 60-120 行；细节放到 `docs/`、`rules/`、`specs/` 或测试文档，并在入口索引引用。
 - 根 `AGENTS.md` 只写全项目都成立的入口规则；目录独有的模块职责、边界、入口、测试命令、坑点和禁止事项，优先写进最接近该目录的子目录 `AGENTS.md`。
+- 新增业务目录、模块职责变化、目录入口变化、目录级测试命令变化时，必须检查并更新最接近该目录的子目录 `AGENTS.md`；不要等 review 发现目录规则缺口后再补。
 - 如果项目同时维护模板源、镜像和运行时副本，先确认哪一份是 canonical；默认优先修改模板 canonical，再同步活跃副本，不要只修当前工作区现状。
 - 每条禁令必须给替代方案；不能说明替代方案的内容先写成风险或待确认项。
 - 可以自动检查的规则优先进入 lint、schema、hook、CI、verify 脚本，不只依赖文字提醒。
@@ -28,9 +29,22 @@
 | 代码地图 | `docs/ai/repo-map.md`、`codemaps/*`、架构索引或模块清单 |
 | 测试入口 | test scripts、`tests/`、Playwright/Cypress/Pytest/Vitest 配置 |
 | 自动化检查 | linter、formatter、typecheck、CI、hooks |
+| 命名与业务词典 | `docs/harness/code-style-and-naming.md`、`docs/code-style.md`、接口 / 数据字典 |
+| 目录级规则覆盖 | `owned_paths`、`docs/ai/repo-map.md`、现有子目录 `AGENTS.md`、模块入口文件 |
 | 私域知识 | 内部组件库、私有 API、特殊目录、历史迁移约束 |
 | Bad Case | 近期 review、bug 标签、trace、失败复盘、团队反复纠正事项 |
 
+最小核心文档集建议至少覆盖：
+
+- `AGENTS.md`
+- `README.md`
+- `docs/architecture.md`
+- `docs/code-style.md`
+- `docs/api-convention.md`
+- `docs/component-map.md`
+- `docs/test-strategy.md`
+- `docs/current-task.md`
+
 ## 根 AGENTS.md 模板
 
 ```markdown
@@ -45,6 +59,7 @@
 - 真实入口：<启动、构建、测试、driver 或任务系统入口>
 - 代码地图：`<docs/ai/repo-map.md 或同类导航文件>`；需要理解模块位置时先读它，再进入具体目录。
 - 如果存在目录级 `AGENTS.md`：进入对应目录后同时遵守根规则和本地规则。
+- 新增业务目录、模块职责变化、目录入口变化、目录级测试命令变化时，必须同步更新对应子目录 `AGENTS.md`。
 - 不要把 README 的业务介绍复制到这里；README 回答“项目是什么”，本文件回答“Agent 怎么改”。
 
 ## 模板与 Canonical
@@ -71,12 +86,40 @@
 | <例如状态管理> | `<existing-pattern>` | <不要引入的新库> |
 | <例如数据访问> | `<repository/service>` | <不要跨层调用> |
 
+常见可直接复用的规则样板：
+
+```text
+前端：
+- 页面只负责展示和组合
+- 业务逻辑放 hooks
+- 接口请求放 services
+- 类型放 types
+- 常量放 constants
+- 公共组件放 components/common
+
+后端：
+- Controller 只处理请求和响应
+- Service 处理业务逻辑
+- Repository/DAO 处理数据库
+- DTO 处理输入输出结构
+```
+
 ## 项目硬约束
 
 - <CRITICAL 规则 1>；替代方案：<明确可执行做法>。
 - <CRITICAL 规则 2>；替代方案：<明确可执行做法>。
 - <安全 / 数据 / 权限 / 迁移 / 发布红线>；替代方案：<明确可执行做法>。
 
+常见禁止事项样板：
+
+```text
+- 禁止在页面组件中直接请求接口；替代方案：统一走 services / API client。
+- 禁止重复封装 axios/fetch；替代方案：复用现有 HTTP client。
+- 禁止在公共组件里写业务逻辑；替代方案：把业务逻辑下沉到 feature 或 hooks。
+- 禁止绕过权限系统；替代方案：复用既有权限入口或 policy。
+- 禁止新增 utils2、common2、helper2 这类目录；替代方案：放回既有模块或补目录级规则后再新增。
+```
+
 ## 测试与完成定义
 
 - 修改 <模块/路径> 后至少运行 `<command>`。
@@ -94,6 +137,7 @@
 
 - 架构：`<docs/architecture.md>`
 - 代码地图：`<docs/ai/repo-map.md>`
+- 代码风格 / 命名：`<docs/harness/code-style-and-naming.md 或 docs/code-style.md>`
 - API / 契约：`<docs/api.md>`
 - 测试策略：`<docs/testing.md>`
 - 部署 / 运维：`<docs/deploy.md>`
@@ -102,7 +146,7 @@
 
 ## 子目录 AGENTS.md 模板
 
-只有 monorepo 或目录规则明显不同时才添加子目录 `AGENTS.md`。子目录规则应比根规则更具体。
+只有 monorepo 或目录规则明显不同时才添加子目录 `AGENTS.md`。一旦目录已具备独立模块职责、入口、测试命令或反复出现局部坑点，就不应继续把规则堆在根入口文件里。
 
 ````markdown
 # <path> AGENTS.md
@@ -111,6 +155,7 @@
 
 - 本文件只适用于 `<path>/` 下的改动。
 - 根 `AGENTS.md` 仍然有效；本文件只补充或收紧本目录规则。
+- 如果存在 `<!-- BEGIN AUTO-MODULE-FACTS -->` 托管区块，它只维护动态事实；手写规则必须保留在托管区块外。
 
 ## 本目录约束
 
@@ -120,12 +165,15 @@
 - 入口文件：<真实入口>
 - 修改前必须先看：<核心文件 / 规则 / 测试>
 - 测试命令：<目录级验证命令>
+- 常见复用对象：<组件 / hook / service / helper / fixture>
+- 常见坑和禁止事项：<本目录专属坑点，以及对应替代方案>
 
 ## 决策表
 
 | 场景 | 应使用 | 不要使用 |
 | --- | --- | --- |
 | <场景> | <本目录模式> | <禁止做法> |
+| 复用同类能力 | <已有组件 / hook / service / helper> | <重复新建一套实现> |
 
 ## 代码示例
 
@@ -161,6 +209,8 @@
 | 是否包含通用编码常识 | 删除 |
 | 是否缺少代码地图入口 | 新增 `docs/ai/repo-map.md` 或说明为什么项目太小不需要 |
 | 是否把目录级规则堆在根 AGENTS.md | 下沉到最接近适用范围的子目录 `AGENTS.md` |
+| 是否新增了独立模块目录却没有子目录 `AGENTS.md` | 立即补齐，至少写职责、边界、入口、测试命令和局部禁止事项 |
+| 子目录 `AGENTS.md` 是否只剩 `AUTO-MODULE-FACTS` 托管区块 | 补手写规则，不要把动态 facts 当成目录规则完成态 |
 | 是否没有说明 canonical | 补充模板源 / 活跃副本 / 运行时副本的优先级 |
 | 禁令是否没有替代方案 | 补替代方案或降级为风险 |
 | 是否引用不存在的命令或路径 | 修正或删除 |