@pzy560117/codex-harness 0.1.2 → 0.1.4

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

@@ -1,16 +1,19 @@
 {
   "runtime": {
-    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/codex-loop.ps1",
+    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/codex-loop.ps1",
     "trace_dir": "traces",
     "agent": "codex",
     "run_profile": ".codex\\task-run-profile.json",
-    "git": {
-      "require_clean_workspace": true,
-      "non_blocking_dirty_paths": []
-    },
-    "session": {
-      "mode": "fresh-process",
-      "carry_forward_summary": false
+    "git": {
+      "require_clean_workspace": true,
+      "non_blocking_dirty_paths": []
+    },
+    "content_gates": {
+      "default_mode": "core"
+    },
+    "session": {
+      "mode": "fresh-process",
+      "carry_forward_summary": false
     },
     "subagents": {
       "mode": "guided",
@@ -64,7 +67,7 @@
       "passes": false,
       "context_files": [
         "AGENTS.md",
-        "tools/harness/templates/project-task-template.json",
+        "tools/harness/templates/project-task-template.json",
         "docs/architecture/constraints.md",
         "docs/product/prd-lite.md",
         "docs/product/acceptance-criteria.md",
@@ -157,15 +160,15 @@
       "execution": {
         "mode": "single"
       },
-      "steps": [
-        "围绕已确认 spec 补齐页面清单、状态矩阵、边界条件、异常流和难点研究",
-        "先从 docs/ai/repo-map.md 或 docs/context/repo-map.md 进入代码结构，再补局部文件阅读；不要直接全仓盲扫",
-        "把 Requirement IDs 映射到界面、状态、接口、测试层级、测试数据和证据路径",
-        "输出可复用的代码理解摘要，至少包含入口、关键调用链、受影响文件、受影响测试和高风险点",
-        "把系统交付形态、公开入口、数据边界、异步边界、测试替身策略和禁止实现写入架构约束 truth source",
-        "生成后续设计和实现必须依赖的 feature-pack、repo-map、architecture-brief 与 testing truth source",
-        "如果任务涉及用户可见行为、路由、表单、权限、状态流转或关键业务闭环，补齐 docs/testing/e2e-plan.md 或同等 feature 级 E2E 计划"
-      ],
+      "steps": [
+        "围绕已确认 spec 补齐页面清单、状态矩阵、边界条件、异常流和难点研究",
+        "先从 docs/ai/repo-map.md 或 docs/context/repo-map.md 进入代码结构，再补局部文件阅读；不要直接全仓盲扫",
+        "把 Requirement IDs 映射到界面、状态、接口、测试层级、测试数据和证据路径",
+        "输出可复用的代码理解摘要，至少包含入口、关键调用链、受影响文件、受影响测试和高风险点",
+        "把系统交付形态、公开入口、数据边界、异步边界、测试替身策略和禁止实现写入架构约束 truth source",
+        "生成后续设计和实现必须依赖的 feature-pack、repo-map、architecture-brief 与 testing truth source",
+        "如果任务涉及用户可见行为、路由、表单、权限、状态流转或关键业务闭环，补齐 docs/testing/e2e-plan.md 或同等 feature 级 E2E 计划"
+      ],
       "test_command": "git diff --check",
       "acceptance": [
         "产品追溯和测试左移文档已补齐且可被后续任务直接消费",
@@ -347,24 +350,24 @@
       "execution": {
         "mode": "single"
       },
-      "steps": [
-        "把后续实现按用户故事顺序映射到 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",
-        "确认每个实现任务都已有 requirement_ids、owned_paths、context_files 和最小可行验收闭环",
-        "对涉及用户可见行为、路由、表单、权限、状态流转或关键业务闭环的任务，明确是否要求 docs/testing/e2e-plan.md，并把相关 E2E 命令写进 test_command 或 release 验证链路",
-        "确认每个 feature_impl 任务都携带 architecture_constraints、forbidden_implementations、tdd_contract 和项目真实可执行的 test_command",
-        "明确哪些故事必须串行，哪些依赖可在后续手工改成并行"
-      ],
+      "steps": [
+        "把后续实现按用户故事顺序映射到 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",
+        "确认每个实现任务都已有 requirement_ids、owned_paths、context_files 和最小可行验收闭环",
+        "对涉及用户可见行为、路由、表单、权限、状态流转或关键业务闭环的任务，明确是否要求 docs/testing/e2e-plan.md，并把相关 E2E 命令写进 test_command 或 release 验证链路",
+        "确认每个 feature_impl 任务都携带 architecture_constraints、forbidden_implementations、tdd_contract 和项目真实可执行的 test_command",
+        "明确哪些故事必须串行，哪些依赖可在后续手工改成并行"
+      ],
       "test_command": "git diff --check",
-      "acceptance": [
-        "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",
-        "高风险用户可见任务已经明确是否需要 e2e-plan 与对应 E2E 证据",
-        "实现任务不会把测试替身、local-only adapter 或领域原型伪装成声明的交付路径",
-        "后续实现与 release 任务的验证边界已经明确且可执行"
-      ]
+      "acceptance": [
+        "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",
+        "高风险用户可见任务已经明确是否需要 e2e-plan 与对应 E2E 证据",
+        "实现任务不会把测试替身、local-only adapter 或领域原型伪装成声明的交付路径",
+        "后续实现与 release 任务的验证边界已经明确且可执行"
+      ]
     },
     {
       "id": "US1-001",
@@ -523,7 +526,7 @@
         "仅实现首个可单独交付的用户故事，并同步补齐其 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')",
+      "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')",
       "acceptance": [
         "US1 能作为 MVP 独立演示或独立验收",
         "US1 满足架构约束 truth source，不以测试替身冒充声明交付路径",
@@ -688,7 +691,7 @@
         "确保 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')",
+      "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')",
       "acceptance": [
         "US2 范围清晰且不与其他故事混杂",
         "US2 满足架构约束 truth source，不以测试替身冒充声明交付路径",
@@ -852,7 +855,7 @@
         "只承接剩余优先级最高且可单独验收的增量，不把 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')",
+      "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')",
       "acceptance": [
         "US3 的增量边界和独立验收方式已明确",
         "US3 满足架构约束 truth source，不以测试替身冒充声明交付路径",
@@ -978,7 +981,7 @@
         "记录失败归因、修复建议、最终通过证据和剩余风险",
         "确认 release 阶段只负责 fresh evidence，不在此阶段第一次补需求或测试范围"
       ],
-      "test_command": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/verify.ps1",
+      "test_command": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/verify.ps1",
       "acceptance": [
         "跨故事完整主流程验证通过，或有明确 blocked 说明与后续处置",
         "P0/P1 回归、契约/API、E2E/视觉或等价系统级验证均有 fresh evidence",

package/package-source/docs/codex-harness-engineering/templates/runtime/scripts/test-install-modes.ps1

@@ -1,3 +1,3 @@
-Set-StrictMode -Version Latest
-$ErrorActionPreference = "Stop"
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
 & (Join-Path $PSScriptRoot 'test-project-root-layout.ps1')

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

@@ -1,52 +1,52 @@
-{
-  "tasks": [
-    {
-      "id": "SMOKE-001",
-      "description": "创建 smoke 结果文件并验证内层 Codex 会话输出边界",
-      "task_kind": "smoke",
-      "gate_profile": "lightweight",
-      "required_truth_sources": [],
-      "priority": 1,
-      "dependencies": [],
-      "passes": false,
-      "context_files": [
-        "AGENTS.md"
-      ],
-      "execution": {
-        "session": {
-          "mode": "fresh-process"
-        },
-        "subagents": {
-          "mode": "off"
-        }
-      },
-      "steps": [
-        "阅读当前仓库的 AGENTS.md",
-        "新建 SMOKE-RESULT.md",
-        "在文件中写入三条简短内容：本仓库是 Codex Harness smoke test；当前任务由内层 Codex 自动实现会话生成结果文件；本次 smoke 仅新增 SMOKE-RESULT.md",
-        "不要修改其他文件",
-        "完成后总结本次修改"
-      ],
-      "test_command": "if (-not (Test-Path -LiteralPath 'SMOKE-RESULT.md')) { exit 1 }; $lines = @(Get-Content -LiteralPath 'SMOKE-RESULT.md'); if ($lines.Count -ne 3) { exit 1 }; foreach ($line in $lines) { if ($line -match '\\s+$') { exit 1 } }; $content = [string]::Join([Environment]::NewLine, $lines); if ($content -notmatch 'Codex Harness smoke test') { exit 1 }; if ($content -notmatch '内层 Codex 自动实现会话生成结果文件') { exit 1 }; if ($content -notmatch '本次 smoke 仅新增 SMOKE-RESULT.md') { exit 1 }; $statusLines = @(git status --short --untracked-files=all); if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }; $changedPaths = @(); foreach ($line in $statusLines) { if (-not [string]::IsNullOrWhiteSpace($line) -and $line.Length -ge 4) { $changedPaths += $line.Substring(3).Trim() } }; if ($changedPaths.Count -ne 1 -or $changedPaths[0] -ne 'SMOKE-RESULT.md') { exit 1 }; git diff --check; exit $LASTEXITCODE",
-      "acceptance": [
-        "SMOKE-RESULT.md 存在",
-        "SMOKE-RESULT.md 明确说明结果文件由内层 Codex 自动实现会话生成",
-        "SMOKE-RESULT.md 明确说明本次 smoke 仅新增 SMOKE-RESULT.md",
-        "内层会话没有修改 task.json、progress.txt 或 traces/"
-      ]
-    }
-  ],
-  "runtime": {
-    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/codex-loop.ps1",
-    "run_profile": ".codex\\task-run-profile.json",
-    "session": {
-      "mode": "fresh-process",
-      "carry_forward_summary": false
-    },
-    "subagents": {
-      "mode": "off",
-      "allowed_roles": [],
-      "max_parallel_roles": 0
-    }
-  }
-}
+{
+  "tasks": [
+    {
+      "id": "SMOKE-001",
+      "description": "创建 smoke 结果文件并验证内层 Codex 会话输出边界",
+      "task_kind": "smoke",
+      "gate_profile": "lightweight",
+      "required_truth_sources": [],
+      "priority": 1,
+      "dependencies": [],
+      "passes": false,
+      "context_files": [
+        "AGENTS.md"
+      ],
+      "execution": {
+        "session": {
+          "mode": "fresh-process"
+        },
+        "subagents": {
+          "mode": "off"
+        }
+      },
+      "steps": [
+        "阅读当前仓库的 AGENTS.md",
+        "新建 SMOKE-RESULT.md",
+        "在文件中写入三条简短内容：本仓库是 Codex Harness smoke test；当前任务由内层 Codex 自动实现会话生成结果文件；本次 smoke 仅新增 SMOKE-RESULT.md",
+        "不要修改其他文件",
+        "完成后总结本次修改"
+      ],
+      "test_command": "if (-not (Test-Path -LiteralPath 'SMOKE-RESULT.md')) { exit 1 }; $lines = @(Get-Content -LiteralPath 'SMOKE-RESULT.md'); if ($lines.Count -ne 3) { exit 1 }; foreach ($line in $lines) { if ($line -match '\\s+$') { exit 1 } }; $content = [string]::Join([Environment]::NewLine, $lines); if ($content -notmatch 'Codex Harness smoke test') { exit 1 }; if ($content -notmatch '内层 Codex 自动实现会话生成结果文件') { exit 1 }; if ($content -notmatch '本次 smoke 仅新增 SMOKE-RESULT.md') { exit 1 }; $statusLines = @(git status --short --untracked-files=all); if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }; $changedPaths = @(); foreach ($line in $statusLines) { if (-not [string]::IsNullOrWhiteSpace($line) -and $line.Length -ge 4) { $changedPaths += $line.Substring(3).Trim() } }; if ($changedPaths.Count -ne 1 -or $changedPaths[0] -ne 'SMOKE-RESULT.md') { exit 1 }; git diff --check; exit $LASTEXITCODE",
+      "acceptance": [
+        "SMOKE-RESULT.md 存在",
+        "SMOKE-RESULT.md 明确说明结果文件由内层 Codex 自动实现会话生成",
+        "SMOKE-RESULT.md 明确说明本次 smoke 仅新增 SMOKE-RESULT.md",
+        "内层会话没有修改 task.json、progress.txt 或 traces/"
+      ]
+    }
+  ],
+  "runtime": {
+    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/codex-loop.ps1",
+    "run_profile": ".codex\\task-run-profile.json",
+    "session": {
+      "mode": "fresh-process",
+      "carry_forward_summary": false
+    },
+    "subagents": {
+      "mode": "off",
+      "allowed_roles": [],
+      "max_parallel_roles": 0
+    }
+  }
+}

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

@@ -1,86 +1,86 @@
-{
-  "session": {
-    "mode": "fresh-process",
-    "reuse_previous_chat": false,
-    "carry_forward_summary": false,
-    "context_sources": [
-      "AGENTS.md",
-      "docs/harness/task-session-strategy.md",
-      "docs/harness/architecture.md",
-      "docs/harness/knowledge-architecture.md",
-      "docs/harness/prompt-knowledge-integration.md",
-      "docs/harness/rule-governance.md",
-      "docs/harness/regression-rules.md",
-      "docs/knowledge/knowledge-catalog.md",
-      "docs/testing/ACCEPTANCE_EXAMPLES.md",
-      "docs/testing/TRACEABILITY_MATRIX.md",
-      "docs/testing/TEST_STRATEGY.md",
-      "docs/testing/TEST_DATA_MATRIX.md",
-      "docs/testing/RISK_BASED_TEST_PLAN.md",
-      "docs/testing/EVIDENCE_PROTOCOL.md",
-      "docs/testing/test-matrix.md",
-      "docs/testing/verify-matrix.md"
-    ]
-  },
-  "subagents": {
-    "mode": "guided",
-    "allowed_roles": [
-      "explorer",
-      "readonly-research",
-      "docs-researcher",
-      "planner",
-      "architect",
-      "reviewer",
-      "stage1-reviewer",
-      "stage2-reviewer",
-      "security-reviewer",
-      "test-planner",
-      "failure-triage",
-      "visual-reviewer",
-      "harness-writer",
-      "docs-worker",
-      "frontend-worker",
-      "backend-worker",
-      "test-runner"
-    ],
-    "max_parallel_roles": 3,
-    "notes": [
-      "Implementation sessions may use subagents to accelerate development when work can be split by ownership, role, or verification boundary.",
-      "Subagents must read the matching AGENTS/rules/docs/skills before concluding.",
-      "Read-only roles stay read-only and return summaries or concrete results, not full transcripts.",
-      "Writer roles must receive explicit allowed paths, forbidden paths, expected output, and verification commands before editing.",
-      "Any repo write outside driver-owned runtime outputs must go to a matching writer role; the controller/main session should not write directly."
-    ]
-  },
-  "modelPolicy": {
-    "defaultModel": "gpt-5.4",
-    "defaultReasoningEffort": "medium",
-    "reasoningEfforts": [
-      "none",
-      "low",
-      "medium",
-      "high",
-      "xhigh"
-    ],
-    "overrideOrder": [
-      "task.execution.modelPolicy",
-      "modelPolicy.default"
-    ],
-    "escalation": {
-      "sameFindingRetry2": {
-        "model": "gpt-5.5",
-        "reasoningEffort": "high"
-      },
-      "sameFindingRetry3": {
-        "model": "gpt-5.5",
-        "reasoningEffort": "xhigh"
-      }
-    }
-  },
-  "workspace": {
-    "mode": "in-place"
-  },
-  "git": {
-    "require_clean_workspace": true
-  }
-}
+{
+  "session": {
+    "mode": "fresh-process",
+    "reuse_previous_chat": false,
+    "carry_forward_summary": false,
+    "context_sources": [
+      "AGENTS.md",
+      "docs/harness/task-session-strategy.md",
+      "docs/harness/architecture.md",
+      "docs/harness/knowledge-architecture.md",
+      "docs/harness/prompt-knowledge-integration.md",
+      "docs/harness/rule-governance.md",
+      "docs/harness/regression-rules.md",
+      "docs/knowledge/knowledge-catalog.md",
+      "docs/testing/ACCEPTANCE_EXAMPLES.md",
+      "docs/testing/TRACEABILITY_MATRIX.md",
+      "docs/testing/TEST_STRATEGY.md",
+      "docs/testing/TEST_DATA_MATRIX.md",
+      "docs/testing/RISK_BASED_TEST_PLAN.md",
+      "docs/testing/EVIDENCE_PROTOCOL.md",
+      "docs/testing/test-matrix.md",
+      "docs/testing/verify-matrix.md"
+    ]
+  },
+  "subagents": {
+    "mode": "guided",
+    "allowed_roles": [
+      "explorer",
+      "readonly-research",
+      "docs-researcher",
+      "planner",
+      "architect",
+      "reviewer",
+      "stage1-reviewer",
+      "stage2-reviewer",
+      "security-reviewer",
+      "test-planner",
+      "failure-triage",
+      "visual-reviewer",
+      "harness-writer",
+      "docs-worker",
+      "frontend-worker",
+      "backend-worker",
+      "test-runner"
+    ],
+    "max_parallel_roles": 3,
+    "notes": [
+      "Implementation sessions may use subagents to accelerate development when work can be split by ownership, role, or verification boundary.",
+      "Subagents must read the matching AGENTS/rules/docs/skills before concluding.",
+      "Read-only roles stay read-only and return summaries or concrete results, not full transcripts.",
+      "Writer roles must receive explicit allowed paths, forbidden paths, expected output, and verification commands before editing.",
+      "Any repo write outside driver-owned runtime outputs must go to a matching writer role; the controller/main session should not write directly."
+    ]
+  },
+  "modelPolicy": {
+    "defaultModel": "gpt-5.4",
+    "defaultReasoningEffort": "medium",
+    "reasoningEfforts": [
+      "none",
+      "low",
+      "medium",
+      "high",
+      "xhigh"
+    ],
+    "overrideOrder": [
+      "task.execution.modelPolicy",
+      "modelPolicy.default"
+    ],
+    "escalation": {
+      "sameFindingRetry2": {
+        "model": "gpt-5.5",
+        "reasoningEffort": "high"
+      },
+      "sameFindingRetry3": {
+        "model": "gpt-5.5",
+        "reasoningEffort": "xhigh"
+      }
+    }
+  },
+  "workspace": {
+    "mode": "in-place"
+  },
+  "git": {
+    "require_clean_workspace": true
+  }
+}

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

@@ -1,16 +1,19 @@
 {
   "runtime": {
-    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/codex-loop.ps1",
+    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/codex-loop.ps1",
     "trace_dir": "traces",
     "agent": "codex",
     "run_profile": ".codex\\task-run-profile.json",
-    "git": {
-      "require_clean_workspace": true,
-      "non_blocking_dirty_paths": []
-    },
-    "session": {
-      "mode": "fresh-process",
-      "carry_forward_summary": false
+    "git": {
+      "require_clean_workspace": true,
+      "non_blocking_dirty_paths": []
+    },
+    "content_gates": {
+      "default_mode": "core"
+    },
+    "session": {
+      "mode": "fresh-process",
+      "carry_forward_summary": false
     },
     "state_compaction": {
       "enabled": true,

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

@@ -7,9 +7,9 @@ param(
 Set-StrictMode -Version Latest
 $ErrorActionPreference = "Stop"
 
-if ([string]::IsNullOrWhiteSpace($ProjectRoot)) {
-  $ProjectRoot = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot "..\.."))
-}
+if ([string]::IsNullOrWhiteSpace($ProjectRoot)) {
+  $ProjectRoot = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot "..\.."))
+}
 
 function Invoke-VerificationCommand {
   param(
@@ -68,12 +68,12 @@ function Get-CandidateHookConfigPaths {
     [string[]]$AdditionalPaths
   )
 
-  return @(
-    (Join-Path $HOME ".codex\hooks.json"),
-    (Join-Path $Root ".codex\hooks.json"),
-    (Join-Path $Root "docs\codex-harness-engineering\templates\hooks\hooks.json")
-  ) + $AdditionalPaths
-}
+  return @(
+    (Join-Path $HOME ".codex\hooks.json"),
+    (Join-Path $Root ".codex\hooks.json"),
+    (Join-Path $Root "docs\codex-harness-engineering\templates\hooks\hooks.json")
+  ) + $AdditionalPaths
+}
 
 function Resolve-HookScriptReference {
   param(
@@ -116,20 +116,20 @@ function Test-HookScriptInstallMapping {
     return $true
   }
 
-  $relativeExpectedPath = "tools\harness\hook-stop-verify.ps1"
+  $relativeExpectedPath = "tools\harness\hook-stop-verify.ps1"
   $normalized = $ResolvedScriptPath.Replace("/", "\")
   if (-not $normalized.EndsWith($relativeExpectedPath, [System.StringComparison]::OrdinalIgnoreCase)) {
     return $false
   }
 
   $templateScript = Join-Path $Root "docs\codex-harness-engineering\templates\hooks\hook-stop-verify.ps1"
-  $bootstrapScript = Join-Path $Root "tools\install\bootstrap-codex-harness.ps1"
+  $bootstrapScript = Join-Path $Root "tools\install\bootstrap-codex-harness.ps1"
   if (-not ((Test-Path -LiteralPath $templateScript) -and (Test-Path -LiteralPath $bootstrapScript))) {
     return $false
   }
 
   $bootstrapText = Get-Content -LiteralPath $bootstrapScript -Raw
-  return $bootstrapText.Contains('hooks\hook-stop-verify.ps1') -and $bootstrapText.Contains('tools\harness\hook-stop-verify.ps1')
+  return $bootstrapText.Contains('hooks\hook-stop-verify.ps1') -and $bootstrapText.Contains('tools\harness\hook-stop-verify.ps1')
 }
 
 function Test-CodexHookCommandCompatibility {
@@ -167,15 +167,15 @@ function Test-PowerShellSyntax {
   param([string]$Root)
 
   $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\verify.ps1",
-    "docs\codex-harness-engineering\templates\bootstrap-codex-harness.ps1",
-    "docs\codex-harness-engineering\templates\hooks\hook-stop-verify.ps1"
-  )
+    "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\verify.ps1",
+    "docs\codex-harness-engineering\templates\bootstrap-codex-harness.ps1",
+    "docs\codex-harness-engineering\templates\hooks\hook-stop-verify.ps1"
+  )
 
   foreach ($relativePath in $paths) {
     $path = Join-Path $Root $relativePath

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

@@ -0,0 +1,15 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放随模板分发的辅助脚本。
+
+## 结构索引
+
+- `ai-workflow/`：AI 配置同步、漂移检查脚本。
+- `harness/`：harness 治理辅助脚本。
+
+## 修改规则
+
+- 这里的脚本应服务模板安装、治理或同步，不要引入项目业务耦合。
+- 修改脚本时同步检查被谁调用：bootstrap、package-assets、文档示例或外部流程。