@pzy560117/codex-harness 0.1.0 → 0.1.1

package/package-source/docs/codex-harness-engineering/templates/config/rules/patterns.md

@@ -0,0 +1,59 @@
+---
+trigger: always_on
+---
+
+# Common Patterns
+
+## API Response Format
+
+```typescript
+interface ApiResponse<T> {
+  success: boolean
+  data?: T
+  error?: string
+  meta?: {
+    total: number
+    page: number
+    limit: number
+  }
+}
+```
+
+## Custom Hooks Pattern
+
+```typescript
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value)
+
+  useEffect(() => {
+    const handler = setTimeout(() => setDebouncedValue(value), delay)
+    return () => clearTimeout(handler)
+  }, [value, delay])
+
+  return debouncedValue
+}
+```
+
+## Repository Pattern
+
+```typescript
+interface Repository<T> {
+  findAll(filters?: Filters): Promise<T[]>
+  findById(id: string): Promise<T | null>
+  create(data: CreateDto): Promise<T>
+  update(id: string, data: UpdateDto): Promise<T>
+  delete(id: string): Promise<void>
+}
+```
+
+## Skeleton Projects
+
+When implementing new functionality:
+1. Search for battle-tested skeleton projects
+2. Use parallel agents to evaluate options:
+   - Security assessment
+   - Extensibility analysis
+   - Relevance scoring
+   - Implementation planning
+3. Clone best match as foundation
+4. Iterate within proven structure

package/package-source/docs/codex-harness-engineering/templates/config/rules/safety.rules

@@ -0,0 +1,35 @@
+prefix_rule(
+    pattern = ["git", "reset", "--hard"],
+    decision = "forbidden",
+    justification = "Never discard user or agent work without explicit human direction outside automation.",
+)
+
+prefix_rule(
+    pattern = ["git", "checkout", "--"],
+    decision = "forbidden",
+    justification = "Destructive checkout can overwrite user work and is not allowed in harness automation.",
+)
+
+prefix_rule(
+    pattern = ["git", "clean"],
+    decision = "forbidden",
+    justification = "Git clean can delete untracked user files and generated evidence.",
+)
+
+prefix_rule(
+    pattern = ["rm", "-rf"],
+    decision = "forbidden",
+    justification = "Recursive deletion is not allowed from agent automation.",
+)
+
+prefix_rule(
+    pattern = ["Remove-Item", "-Recurse"],
+    decision = "forbidden",
+    justification = "Recursive deletion must not run from broad agent automation.",
+)
+
+prefix_rule(
+    pattern = ["powershell", "-NoProfile", "-Command", "Remove-Item"],
+    decision = "prompt",
+    justification = "PowerShell deletion must be reviewed because inline commands can be broad or destructive.",
+)

package/package-source/docs/codex-harness-engineering/templates/config/rules/testing.md

@@ -0,0 +1,34 @@
+---
+trigger: always_on
+---
+
+# Testing Requirements
+
+## Minimum Test Coverage: 80%
+
+Test Types (ALL required):
+1. **Unit Tests** - Individual functions, utilities, components
+2. **Integration Tests** - API endpoints, database operations
+3. **E2E Tests** - Critical user flows (Playwright)
+
+## Test-Driven Development
+
+MANDATORY workflow:
+1. Write test first (RED)
+2. Run test - it should FAIL
+3. Write minimal implementation (GREEN)
+4. Run test - it should PASS
+5. Refactor (IMPROVE)
+6. Verify coverage (80%+)
+
+## Troubleshooting Test Failures
+
+1. Use **tdd-guide** agent
+2. Check test isolation
+3. Verify mocks are correct
+4. Fix implementation, not tests (unless tests are wrong)
+
+## Agent Support
+
+- **tdd-guide** - Use PROACTIVELY for new features, enforces write-tests-first
+- **e2e-runner** - Playwright E2E testing specialist

package/package-source/docs/codex-harness-engineering/templates/context/architecture-brief.md

@@ -0,0 +1,58 @@
+# Architecture Brief
+
+## 1. 系统概览
+
+- 系统边界: 本仓库维护 Codex Harness 安装包和当前仓库运行时，不承载具体业务应用。
+- 核心服务: `tools/harness/codex-loop.ps1` driver、`tools/install/bootstrap-codex-harness.ps1` 安装初始化、`refresh-agent-package.ps1` 包同步、`.codex/prompts/*` 执行提示、`.agents/skills/*` 可复用技能。
+- 主要数据流: `task.json` -> driver -> `codex exec` -> 验证命令 -> `progress.txt` / trace -> Git commit。
+
+## 2. 分层职责
+
+| 层 | 职责 | 主要目录 |
+| --- | --- | --- |
+| Runtime 层 | 任务选择、执行、验证、trace、提交 | `tools/harness/codex-loop.ps1`, `task.json`, `.codex/` |
+| Package 层 | 当前仓库包根与可分发 package-assets | repo root |
+| Template 层 | 新项目 bootstrap 模板 | `docs/codex-harness-engineering/templates/` |
+| Knowledge 层 | 深文档、规则治理、测试真相源、知识沉淀 | `docs/harness/`, `docs/testing/`, `docs/knowledge/` |
+| Skill 层 | 可复用流程和专用能力 | `.agents/skills/`, `docs/codex-harness-engineering/templates/package-assets/skills/` |
+
+## 3. 真相源
+
+- 产品真相源: `docs/requirement-prep-kit/` 或任务声明。
+- 设计真相源: `docs/codex-harness-engineering/templates/design/`。
+- Contract 真相源: `docs/codex-harness-engineering/templates/contracts/`。
+- 类型真相源: PowerShell scripts、JSON schema、task template。
+- 测试真相源: `docs/testing/*`。
+
+## 4. 关键模块
+
+| 模块 | 责任 | 上游 | 下游 | 风险 |
+| --- | --- | --- | --- | --- |
+| `tools/harness/codex-loop.ps1` | driver-first 自动执行 | `task.json`, `.codex/prompts/*` | trace、progress、commit | 状态伪造、验证缺失 |
+| `tools/install/bootstrap-codex-harness.ps1` | 初始化目标项目 runtime/docs/config | templates | 目标项目根目录 | 漏装关键 truth source |
+| `refresh-agent-package.ps1` | 刷新当前仓库 package 面和 manifest | root truth source | templates / ai-sync | 镜像漂移 |
+| `.agents/skills/` | 活跃技能 canonical | skill authors | `docs/codex-harness-engineering/templates/package-assets/skills`, package-assets | 只改一处导致分发缺失 |
+| `docs/codex-harness-engineering/` | 安装包方法论和模板 | root docs / package docs | package-assets docs | 文档和安装行为不一致 |
+
+## 5. 关键约束
+
+- 修改安装行为时，先改 root runtime 或模板 canonical，再同步 `.agents/`、templates 和 package-assets。
+- 修改 skills 时，以 `.agents/skills/<name>` 为 canonical。
+- 修改 active role rules 时，以 `.codex/rules/agents.md` 为 canonical。
+- 文档改动至少运行 `git diff --check`；脚本改动还要做 PowerShell parser 检查。
+
+## 6. 高风险区域
+
+- `task.json` 状态写回。
+- Git dirty workspace 检查。
+- package mirrors 和 manifest / lock。
+- hooks 与 driver 职责边界。
+- 外部 MCP、token、cookie、私钥、密码。
+
+## 7. 建议阅读顺序
+
+1. `AGENTS.md`
+2. `docs/ai/repo-map.md`
+3. `docs/harness/architecture.md`
+4. `docs/harness/rule-governance.md`
+5. `docs/codex-harness-engineering/README.md`

package/package-source/docs/codex-harness-engineering/templates/context/dev-plan.md

@@ -0,0 +1,160 @@
+# DEV-PLAN 模板
+
+## 1. 基本信息
+
+- `feature_id`:
+- `title`:
+- `owner`:
+- `source_docs`:
+  - `docs/product/...`
+  - `docs/design/...`
+  - `contracts/...`
+
+## 2. 目标与完成定义
+
+- 业务目标:
+- 技术目标:
+- Done 定义:
+
+## 3. 真相源
+
+- Product Spec:
+- PRD-Lite:
+- Page Inventory:
+- State Matrix:
+- Acceptance Criteria:
+- Acceptance Examples:
+- Requirement Interface Matrix:
+- Traceability Matrix:
+- Difficulty Research:
+- Design Brief:
+- 设计稿 / Figma:
+- Component Map:
+- Screen States:
+- Design Tokens:
+- AI Image Brief:
+- UI Image Review:
+- Image To Frontend Spec:
+- Visual Parity Review:
+- Contract:
+- Test Matrix:
+- E2E Plan:
+- Test Data Plan:
+- Test Data Matrix:
+- Risk Based Test Plan:
+- Regression Plan:
+- Evidence Protocol:
+- Failure Triage:
+- Coverage Policy:
+- Verify Matrix:
+- Repo map:
+
+## 4. 阶段闸门
+
+| 阶段 | 进入条件 | 输出 | 未满足时处理 |
+| --- | --- | --- | --- |
+| Product Readiness | 原始需求已澄清，P0/P1 需求已补齐验收标准、验收示例和追溯入口 | `docs/product/*`, `ACCEPTANCE_CRITERIA.md`, `ACCEPTANCE_EXAMPLES.md`, `TRACEABILITY_MATRIX.md` | BLOCKED 或补需求 |
+| Design Readiness | Product Readiness 通过 | `docs/design/*` | BLOCKED 或补设计 |
+| UI Image Readiness | CSS/视觉规范完整，AI 生图已评审 | `ai-image-brief.md`, `ui-image-review.md`, `image-to-frontend-spec.md` | BLOCKED 或重生成/编辑图片 |
+| Visual Parity Readiness | 前端页面已实现并可在浏览器打开 | `artifacts/visual-review/*`, `visual-parity-review.md` | BLOCKED 或修复 UI 后重新截图 |
+| Test Readiness | P0/P1 需求已映射到测试层级、测试数据、affected tests、evidence path 和回归范围 | `test-matrix.md`, `TEST_DATA_MATRIX.md`, `RISK_BASED_TEST_PLAN.md`, `REGRESSION_PLAN.md`, `failure-triage.md` | BLOCKED 或补测试计划 |
+| Contract Readiness | API / 数据变化已明确 | `contracts/openapi.yaml` | BLOCKED 或豁免说明 |
+| Implementation | Product、Design、Plan、Testing 真相源齐全，Requirement IDs 已可追溯 | 代码、测试、trace | 禁止实现 |
+
+## 5. Phase 划分
+
+### Phase 1
+
+- 目标:
+- 交付物:
+- 前置条件:
+- 风险:
+
+### Phase 2
+
+- 目标:
+- 交付物:
+- 前置条件:
+- 风险:
+
+### Phase 3
+
+- 目标:
+- 交付物:
+- 前置条件:
+- 风险:
+
+## 6. Task 拆分规则
+
+- 每个 Task 只处理一个明确目标。
+- 每个 Task 必须能在 fresh session 中完成。
+- 每个 Task 必须有自己的验证命令。
+- 每个实现 Task 必须声明 Requirement IDs、owned paths、affected tests 和 evidence expectation。
+- 不允许把“实现 + 修所有 bug + 补所有测试”混成一个任务。
+
+## 7. 当前 Task 队列
+
+| Task ID | Phase | 目标 | 依赖 | 验证命令 | 状态 |
+| --- | --- | --- | --- | --- | --- |
+| T001 | P1 | | | | todo |
+
+## 8. 评审与修复闭环
+
+```text
+实现
+  -> Stage 1 review（Spec / 设计稿 / DEV-PLAN 一致性）
+  -> 浏览器截图与设计参考图视觉还原对比
+  -> 修复偏差
+  -> Stage 2 review（代码质量 / 测试 / 风险）
+  -> 修复问题
+  -> verify + fresh evidence
+  -> 才允许完成
+```
+
+## 9. 验证矩阵
+
+- 类型检查:
+- Lint:
+- Acceptance / Examples:
+- Traceability:
+- 单元测试:
+- 组件 / Story 测试:
+- Contract 测试:
+- API integration:
+- 集成测试:
+- E2E:
+- Affected Tests:
+- P0/P1 Regression:
+- Visual regression:
+- Visual parity screenshots:
+- Contract validation:
+- Coverage:
+- Verify matrix:
+
+## 10. BLOCKED 条件
+
+- 缺少设计稿或状态矩阵
+- 缺少 PRD-Lite、页面清单或验收标准
+- 缺少可执行验收示例
+- 缺少需求到界面的完整追溯矩阵
+- 缺少 `TRACEABILITY_MATRIX.md` 或 Requirement IDs 无法落到代码/测试
+- 高风险难点没有研究结论
+- 缺少 Design Brief、Component Map、Screen States 或 Design Tokens
+- AI 生成界面图未评审通过
+- 图片未转换成前端可实现规格
+- 前端 UI 缺少真实浏览器截图和设计参考图对比报告
+- Contract 未冻结
+- P0/P1 需求缺少 `test-matrix.md` 映射
+- P0/P1 需求缺少 `TEST_DATA_MATRIX.md`、`REGRESSION_PLAN.md` 或 affected tests
+- E2E 缺少 seed 或账号数据
+- 测试失败没有 failure class 和 owner hint
+- 把 Stage 17 当成第一次定义测试范围的入口
+- 依赖任务未完成
+- 关键环境不可用
+- 需要人工决策
+
+## 11. 跨 Session 接续规则
+
+- 新 session 开始时先读本文件。
+- 进入新 Phase 前先重新读取真相源文档。
+- 如果设计稿、Product Spec、Contract 有变更，先更新本计划再编码。

package/package-source/docs/codex-harness-engineering/templates/context/feature-pack.md

@@ -0,0 +1,101 @@
+# Feature Pack 模板
+
+## 1. 基本信息
+
+- `feature_id`: `FEAT-000`
+- `title`: `示例：工单筛选与保存视图`
+- `source`: `issue / requirement doc / incident / cron`
+- `owner`: `Hermes / PM / Engineer`
+- `risk_level`: `L1`
+- `auto_merge_allowed`: `false`
+
+## 2. 业务目标
+
+- 这次变更要解决什么问题？
+- 成功后的业务结果如何判断？
+- 本期不解决什么问题？
+- 哪些开放问题会阻塞后续阶段？
+
+## 3. 影响范围
+
+- 页面:
+- 接口:
+- 目录:
+- 数据表:
+- 权限:
+- 外部系统:
+
+## 4. 需求分析真相源
+
+| 产物 | 路径 | 状态 | 备注 |
+| --- | --- | --- | --- |
+| PRD-Lite | `docs/product/prd-lite.md` | Draft / Approved / N/A | |
+| Page Inventory | `docs/product/page-inventory.md` | Draft / Approved / N/A | |
+| State Matrix | `docs/product/state-matrix.yaml` | Draft / Approved / N/A | |
+| Acceptance Criteria | `docs/product/acceptance-criteria.md` | Draft / Approved / N/A | |
+| Requirement Interface Matrix | `docs/product/requirement-interface-matrix.md` | Draft / Approved / N/A | |
+| Difficulty Research | `docs/product/difficulty-research.md` | Draft / Approved / N/A | |
+
+## 5. 设计真相源
+
+| 产物 | 路径 | 状态 | 备注 |
+| --- | --- | --- | --- |
+| Design Brief | `docs/design/design-brief.md` | Draft / Approved / N/A | |
+| Component Map | `docs/design/component-map.md` | Draft / Approved / N/A | |
+| Screen States | `docs/design/screen-states.md` | Draft / Approved / N/A | |
+| Design Tokens | `docs/design/design-tokens.json` | Draft / Approved / N/A | |
+| AI Image Brief | `docs/design/ai-image-brief.md` | Draft / Approved / N/A | |
+| UI Image Review | `docs/design/ui-image-review.md` | Draft / Approved / N/A | |
+| Image To Frontend Spec | `docs/design/image-to-frontend-spec.md` | Draft / Approved / N/A | |
+
+## 6. 先决条件
+
+- 已存在的能力:
+- 依赖功能:
+- 环境要求:
+
+## 7. 状态矩阵
+
+- `default`:
+- `empty`:
+- `loading`:
+- `error`:
+- `disabled`:
+- `permission_denied`:
+- `long_content`:
+- `responsive/mobile`:
+
+## 8. 变更边界
+
+- 允许修改:
+- 禁止修改:
+- 生成代码目录:
+- 手写代码目录:
+
+## 9. 验收标准
+
+- [ ] 用户可以完成核心流程
+- [ ] 异常流有明确行为
+- [ ] 文档、contract、代码一致
+
+## 10. 验证命令
+
+```powershell
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+## 11. 输出要求
+
+- 需要更新的文档:
+- 需要补充的测试:
+- 需要生成的 client/types/mock:
+- 需要提交的 PR / issue / trace:
+
+## 12. 升级条件
+
+- 哪些情况必须 BLOCKED:
+- 哪些情况必须人工审批:
+- 哪些情况禁止自动合并:

package/package-source/docs/codex-harness-engineering/templates/context/repo-map.md

@@ -0,0 +1,78 @@
+# Repo Map
+
+更新时间: 2026-05-20
+维护责任: Harness package maintainer
+
+## 1. 仓库目标
+
+- 项目一句话描述: Codex Harness 安装实现包，用于把 AGENTS、driver、rules、prompts、skills、hooks、testing truth source 和 package docs 安装到目标项目。
+- 主要用户: 在 Windows / PowerShell 环境中使用 Codex CLI 的项目维护者和自动化执行 agent。
+- 核心业务域: driver-first 任务执行、安装包分发、规则治理、测试左移、知识沉淀、agent 能力同步。
+
+## 2. 从哪里开始读
+
+- 第一步先读: `AGENTS.md`
+- 第二步再读: `docs/ai/architecture-brief.md`
+- 第三步按任务进入:
+  - 安装链路: `tools/install/install-agent.ps1`, `tools/install/bootstrap-codex-harness.ps1`
+  - driver 链路: `tools/harness/codex-loop.ps1`, `.codex/prompts/*`
+  - 分发同步: `refresh-agent-package.ps1`, `.ai-sync.yml`
+  - 规则治理: `docs/harness/rule-governance.md`
+  - 包文档: `docs/codex-harness-engineering/*`
+
+## 3. 关键目录
+
+| 路径 | 用途 | 可修改性 | 备注 |
+| --- | --- | --- | --- |
+| repo root | 当前安装包包根 | 可改 | 新项目安装时主要来源 |
+| `.agents/` | 当前仓库活跃 package / skills 镜像 | 可改 | skills 以这里为活跃 canonical |
+| `.codex/` | 当前仓库 Codex roles、prompts、rules | 可改 | active role rules 以 `.codex/rules/agents.md` 为 canonical |
+| `docs/harness/` | driver、规则、知识、回归等深文档 | 可改 | root truth source |
+| `docs/testing/` | 测试左移真相源 | 可改 | feature_impl 前置输入 |
+| `docs/ai/` | AI 导航索引和架构摘要 | 可改 | 大型项目导航层 |
+| `docs/codex-harness-engineering/templates/` | 安装模板源 | 可改 | 会影响新项目 bootstrap |
+| `docs/codex-harness-engineering/templates/package-assets/` | 安装到目标 `.agents/` 的能力包 | 可改 | 需同步 `.agents` 镜像 |
+| `scripts/` | 辅助验证和同步脚本 | 谨慎 | 修改后做 PowerShell parser 检查 |
+
+## 4. 关键依赖关系
+
+- root runtime -> `refresh-agent-package.ps1` -> templates / package-assets mirrors。
+- root docs -> `templates/package-assets/docs/codex-harness-engineering/` -> 目标项目 `.agents/docs/...`。
+- `.agents/skills/<name>` -> `docs/codex-harness-engineering/templates/package-assets/skills/<name>` -> package-assets skill mirrors。
+- `tools/install/bootstrap-codex-harness.ps1` -> 目标项目根 runtime、`.codex/`、`docs/harness/`、`docs/testing/`、`docs/ai/`。
+
+## 5. 常用命令
+
+```powershell
+git status --short
+git diff --check
+powershell -NoProfile -ExecutionPolicy Bypass -File .\refresh-agent-package.ps1 -RepoRoot . -PackageRoot agent -Surface all -CheckOnly
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/verify.ps1
+```
+
+## 6. 禁改区
+
+- 禁止手工伪造 `task.json` 的 `passes=true`；应让 driver 验证后写回。
+- 禁止跳过 package mirrors：涉及 `.agents/`、templates、package-assets、skills 的改动必须按同步矩阵刷新。
+- 禁止把 token、cookie、私钥、密码写入 docs、trace、prompt 或 package。
+- 禁止在未确认时使用破坏性 Git 命令或递归删除。
+
+## 7. 任务入口
+
+- Feature plan 所在位置: `task.json` 或 `tools/harness/templates/project-task-template.json`
+- Product docs 所在位置: `docs/product/` 或 `docs/requirement-prep-kit/`
+- Design docs 所在位置: `docs/codex-harness-engineering/templates/design/`
+- Contract 所在位置: `docs/codex-harness-engineering/templates/contracts/`
+
+## 8. 子目录规则索引
+
+| 路径 | 本地规则 | 触发场景 |
+| --- | --- | --- |
+| repo root | `AGENTS.md` | 验证安装包入口规则和可分发文件 |
+| `.agents/` | `.agents/AGENTS.md` | 修改活跃 skills / workflows 镜像 |
+
+## 9. 维护规则
+
+- 新增安装时应落地的模板文件时，同时检查 `tools/install/bootstrap-codex-harness.ps1` 和 `.ai-sync.yml`。
+- 新增 package docs 时，同时更新 `docs/codex-harness-engineering/README.md` 和 package-assets 镜像。
+- 更新 skills 时，以 `.agents/skills/<name>` 为 canonical，再同步到 `docs/codex-harness-engineering/templates/package-assets/skills/<name>` 和两套 package-assets。

package/package-source/docs/codex-harness-engineering/templates/context/service-dependency-matrix.yaml

@@ -0,0 +1,25 @@
+version: 1
+status: draft
+usage: "Optional truth source for multi-service, multi-repo, contract, or external-system work. Set status to not_applicable when the project has no cross-service dependency surface."
+services:
+  - service_id: "replace-with-service-or-app-id"
+    repo_path: "replace-with-repo-or-local-path"
+    owner: "replace-with-owner"
+    status: "needs-confirmation"
+    entrypoints:
+      - type: "replace-with-http|grpc|graphql|mq|cli|ui-route|package-api|worker|file-format|none"
+        path: "replace-with-entrypoint"
+    contracts:
+      - type: "replace-with-openapi|protobuf|graphql|typed-api|schema|event|file-format|none"
+        source: "replace-with-contract-path-or-not_applicable"
+        compatibility: "replace-with-backward-compatible|breaking|not_applicable|needs-confirmation"
+    upstream:
+      - "replace-with-caller-or-not_applicable"
+    downstream:
+      - "replace-with-dependency-or-not_applicable"
+    change_gates:
+      - "replace-with-contract-diff-or-api-test"
+      - "replace-with-affected-regression"
+    rollback:
+      strategy: "replace-with-feature-flag|revert|schema-rollback|not_applicable|needs-confirmation"
+      evidence: "replace-with-runbook-or-evidence-path"

package/package-source/docs/codex-harness-engineering/templates/contracts/README.md

@@ -0,0 +1,16 @@
+# Contracts Templates Guide
+
+本目录提供 contract-first 开发的最小模板组合。
+
+## 推荐文件
+
+- `openapi.yaml`: 前后端共享真相源的 OpenAPI 样例
+- `orval.config.ts`: 生成 types / client / mocks 的 Orval 配置模板
+- `prism-usage.md`: 本地 mock server 和 validation proxy 的 Prism 用法模板
+
+## 推荐顺序
+
+1. 先完善 `openapi.yaml`
+2. 再配置 `orval.config.ts`
+3. 生成 client / mocks
+4. 用 `prism-usage.md` 跑本地 mock 与 contract 验证