@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/.specify/templates/spec-template.md

@@ -21,63 +21,63 @@
 - **NG-001**: [Explicitly excluded capability, scenario, or user group]
 - **NG-002**: [Explicitly deferred behavior]
 
-### Scope
-
-| Scope Area | In Scope | Out of Scope |
-| --- | --- | --- |
-| Users / Roles | | |
-| Pages / Flows | | |
-| Data / Entities | | |
-| Integrations | | |
-
-## Delivery Intent & Integration Boundary *(mandatory)*
-
-> Fill this section before writing FRs. If the user has not confirmed whether this is a prototype or a real integration effort, stop and clarify first.
-
-### Delivery Mode
-
-| Field | Value |
-| --- | --- |
-| Delivery Mode | `prototype` / `spike` / `integration` / `production` |
-| User Confirmation | |
-| Can local mock/sample close acceptance? | Yes / No |
-| Formal requirements left incomplete after downgrade | |
-
-### External Systems & Existing Stack
-
-| Integration ID | Related Requirements | Target System / OSS | Required Outcome | Prototype Allowed? | Notes |
-| --- | --- | --- | --- | --- | --- |
-| INT-001 | FR-001 | | | Yes / No | |
-
-## Requirement Enrichment Gate *(mandatory)*
-
-> Separate what the user explicitly said from what the agent inferred. Safe engineering defaults may be added as assumptions; business-changing decisions must remain open or blocked.
-
-### Requirement Source Inventory
-
-| Item ID | Requirement / Gap | Source Type | Source Location | Handling |
-| --- | --- | --- | --- | --- |
-| REQ-SRC-001 | | Explicit / Inferred / Decision Required | User input / best practice / project constraint | Add to FR / Add to NFR / Assumption / [NEEDS CLARIFICATION] / Blocked |
-
-### Inferred Requirements
-
-| Inferred ID | Derived Requirement | Basis | Related FR/NFR | Validation Method | Impact If Wrong |
-| --- | --- | --- | --- | --- | --- |
-| INF-001 | | Domain norm / engineering baseline / official docs / existing code | FR-001 | | |
-
-### Decision Required / Blocked Items
-
-| Decision ID | Question / Missing Item | Why Agent Cannot Decide | Affected Requirements | Status |
-| --- | --- | --- | --- | --- |
-| DEC-001 | | Changes scope / compliance / pricing / brand promise / external dependency | FR-001 | Open / Blocked / Resolved |
-
-### P0/P1 Readiness Gate
-
-| Requirement ID | Acceptance Criteria | Test Data | Observable Oracle | Evidence Path | Executable Verification | Readiness |
-| --- | --- | --- | --- | --- | --- | --- |
-| FR-001 | Present / Missing | Present / Missing | Present / Missing | Present / Missing | Present / Missing | Ready / Needs Clarification / Blocked |
-
-## User Scenarios & Testing *(mandatory)*
+### Scope
+
+| Scope Area | In Scope | Out of Scope |
+| --- | --- | --- |
+| Users / Roles | | |
+| Pages / Flows | | |
+| Data / Entities | | |
+| Integrations | | |
+
+## Delivery Intent & Integration Boundary *(mandatory)*
+
+> Fill this section before writing FRs. If the user has not confirmed whether this is a prototype or a real integration effort, stop and clarify first.
+
+### Delivery Mode
+
+| Field | Value |
+| --- | --- |
+| Delivery Mode | `prototype` / `spike` / `integration` / `production` |
+| User Confirmation | |
+| Can local mock/sample close acceptance? | Yes / No |
+| Formal requirements left incomplete after downgrade | |
+
+### External Systems & Existing Stack
+
+| Integration ID | Related Requirements | Target System / OSS | Required Outcome | Prototype Allowed? | Notes |
+| --- | --- | --- | --- | --- | --- |
+| INT-001 | FR-001 | | | Yes / No | |
+
+## Requirement Enrichment Gate *(mandatory)*
+
+> Separate what the user explicitly said from what the agent inferred. Safe engineering defaults may be added as assumptions; business-changing decisions must remain open or blocked.
+
+### Requirement Source Inventory
+
+| Item ID | Requirement / Gap | Source Type | Source Location | Handling |
+| --- | --- | --- | --- | --- |
+| REQ-SRC-001 | | Explicit / Inferred / Decision Required | User input / best practice / project constraint | Add to FR / Add to NFR / Assumption / [NEEDS CLARIFICATION] / Blocked |
+
+### Inferred Requirements
+
+| Inferred ID | Derived Requirement | Basis | Related FR/NFR | Validation Method | Impact If Wrong |
+| --- | --- | --- | --- | --- | --- |
+| INF-001 | | Domain norm / engineering baseline / official docs / existing code | FR-001 | | |
+
+### Decision Required / Blocked Items
+
+| Decision ID | Question / Missing Item | Why Agent Cannot Decide | Affected Requirements | Status |
+| --- | --- | --- | --- | --- |
+| DEC-001 | | Changes scope / compliance / pricing / brand promise / external dependency | FR-001 | Open / Blocked / Resolved |
+
+### P0/P1 Readiness Gate
+
+| Requirement ID | Acceptance Criteria | Test Data | Observable Oracle | Evidence Path | Executable Verification | Readiness |
+| --- | --- | --- | --- | --- | --- | --- |
+| FR-001 | Present / Missing | Present / Missing | Present / Missing | Present / Missing | Present / Missing | Ready / Needs Clarification / Blocked |
+
+## User Scenarios & Testing *(mandatory)*
 
 <!--
   IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
@@ -137,47 +137,47 @@
 
 [Add more user stories as needed, each with an assigned priority]
 
-### Edge Cases
-
-<!--
-  ACTION REQUIRED: The content in this section represents placeholders.
-  Fill them out with the right edge cases.
+### Edge Cases
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right edge cases.
 -->
 
-- What happens when [boundary condition]?
-- How does system handle [error scenario]?
-
-## Testability & Acceptance Evidence *(mandatory)*
-
-> This section is the left-shift testing entry point. It does not replace later automated tests, but it must make every P0/P1 requirement observable before implementation planning starts.
-
-### Requirement Testability Map
-
-| Requirement ID | Priority | Observable Result | Positive Example | Negative / Edge Example | Required Test Data | Evidence Path | Testability |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| FR-001 | P0 | | Given / When / Then | Given / When / Then | | `docs/evidence/<feature>/fr-001.md` | Ready / Needs Clarification / Blocked / Prototype Only |
-
-### Acceptance Example Seeds
-
-| Scenario ID | Requirement ID | Actor / Role | Given | When | Then | Observable Oracle |
-| --- | --- | --- | --- | --- | --- | --- |
-| AE-001 | FR-001 | | | | | |
-
-### Testing Preconditions
-
-| Blocker ID | Related Requirements | Missing Environment / Data / Permission / Endpoint | Why It Blocks Verification | Status |
-| --- | --- | --- | --- | --- |
-| TBD-TEST-001 | FR-001 | | | Open / Resolved / N/A |
-
-Rules:
-
-- `integration` / `production` requirements cannot be marked testable when required endpoints, credentials, RBAC, fixtures, dashboards, webhooks, or downstream environments are missing.
-- `prototype` / `spike` work may use demo evidence, but must mark formal `FR-*` as incomplete unless the user explicitly accepts the downgrade.
-- Avoid vague oracle wording such as "looks normal"; use response fields, UI states, transcript paths, logs, screenshots, metrics, or failure messages.
-
-## Pages, States & Permissions *(mandatory for UI-facing features)*
-
-### Page Inventory
+- What happens when [boundary condition]?
+- How does system handle [error scenario]?
+
+## Testability & Acceptance Evidence *(mandatory)*
+
+> This section is the left-shift testing entry point. It does not replace later automated tests, but it must make every P0/P1 requirement observable before implementation planning starts.
+
+### Requirement Testability Map
+
+| Requirement ID | Priority | Observable Result | Positive Example | Negative / Edge Example | Required Test Data | Evidence Path | Testability |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| FR-001 | P0 | | Given / When / Then | Given / When / Then | | `docs/evidence/<feature>/fr-001.md` | Ready / Needs Clarification / Blocked / Prototype Only |
+
+### Acceptance Example Seeds
+
+| Scenario ID | Requirement ID | Actor / Role | Given | When | Then | Observable Oracle |
+| --- | --- | --- | --- | --- | --- | --- |
+| AE-001 | FR-001 | | | | | |
+
+### Testing Preconditions
+
+| Blocker ID | Related Requirements | Missing Environment / Data / Permission / Endpoint | Why It Blocks Verification | Status |
+| --- | --- | --- | --- | --- |
+| TBD-TEST-001 | FR-001 | | | Open / Resolved / N/A |
+
+Rules:
+
+- `integration` / `production` requirements cannot be marked testable when required endpoints, credentials, RBAC, fixtures, dashboards, webhooks, or downstream environments are missing.
+- `prototype` / `spike` work may use demo evidence, but must mark formal `FR-*` as incomplete unless the user explicitly accepts the downgrade.
+- Avoid vague oracle wording such as "looks normal"; use response fields, UI states, transcript paths, logs, screenshots, metrics, or failure messages.
+
+## Pages, States & Permissions *(mandatory for UI-facing features)*
+
+### Page Inventory
 
 | Page ID | Page / View | Entry / Route | Actor | Core Goal | Required States | Related Requirements |
 | --- | --- | --- | --- | --- | --- | --- |
@@ -195,47 +195,47 @@ Rules:
 | --- | --- | --- | --- | --- |
 | View | Allowed | Read-only | Denied | |
 
-## Requirements *(mandatory)*
-
-<!--
-  ACTION REQUIRED: The content in this section represents placeholders.
-  Fill them out with the right functional requirements.
--->
-
-> If the current delivery mode is `prototype` or `spike`, do not present demo-only deliverables as completed formal `FR-*`. Use the optional `PROTO-*` / `SPIKE-*` section below to represent exploratory or demo scope.
-
-### Functional Requirements
-
-- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
-- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]  
+## Requirements *(mandatory)*
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+> If the current delivery mode is `prototype` or `spike`, do not present demo-only deliverables as completed formal `FR-*`. Use the optional `PROTO-*` / `SPIKE-*` section below to represent exploratory or demo scope.
+
+### Functional Requirements
+
+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]  
 - **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
 - **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
 - **FR-005**: System MUST [behavior, e.g., "log all security events"]
 
 *Example of marking unclear requirements:*
 
-- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
-- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
-
-### Prototype / Spike Deliverables *(optional)*
-
-- **PROTO-001**: [demo-only or local prototype capability]
-- **SPIKE-001**: [exploratory validation, not a formal delivered requirement]
-- **INTEGRATION-001**: [connector, environment, or evidence preparation work that must finish before FR closure]
-
-### Business Rules
-
-| Rule ID | Rule | Trigger | Validation / Decision Logic | Failure Behavior |
-| --- | --- | --- | --- | --- |
-| BR-001 | | | | |
-
-### External Dependency Preconditions *(include when integrations exist)*
-
-| Blocker ID | Related Requirements | Missing Dependency / Evidence | Impact If Open | Status |
-| --- | --- | --- | --- | --- |
-| TBD-001 | FR-001 | | | Open / Resolved |
-
-### Key Entities *(include if feature involves data)*
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+
+### Prototype / Spike Deliverables *(optional)*
+
+- **PROTO-001**: [demo-only or local prototype capability]
+- **SPIKE-001**: [exploratory validation, not a formal delivered requirement]
+- **INTEGRATION-001**: [connector, environment, or evidence preparation work that must finish before FR closure]
+
+### Business Rules
+
+| Rule ID | Rule | Trigger | Validation / Decision Logic | Failure Behavior |
+| --- | --- | --- | --- | --- |
+| BR-001 | | | | |
+
+### External Dependency Preconditions *(include when integrations exist)*
+
+| Blocker ID | Related Requirements | Missing Dependency / Evidence | Impact If Open | Status |
+| --- | --- | --- | --- | --- |
+| TBD-001 | FR-001 | | | Open / Resolved |
+
+### Key Entities *(include if feature involves data)*
 
 - **[Entity 1]**: [What it represents, key attributes without implementation]
 - **[Entity 2]**: [What it represents, relationships to other entities]
@@ -246,20 +246,20 @@ Rules:
 | --- | --- | --- | --- | --- | --- | --- |
 | | | | | | | |
 
-## Non-Functional Requirements *(mandatory)*
-
-> Evaluate every category. If a category is not applicable, state the reason instead of leaving it blank.
-
-| Category | Requirement / Not Applicable Reason | Target / Standard | Priority | Verification |
-| --- | --- | --- | --- | --- |
-| Performance | | | P0 | |
-| Security / Privacy | | | P0 | |
-| Accessibility | | | P1 | |
-| Compatibility | | | P1 | |
-| Availability / Recovery | | | P1 | |
-| Observability | | | P1 | |
-| Data Consistency | | | P1 | |
-| Deployment / Operations | | | P1 | |
+## Non-Functional Requirements *(mandatory)*
+
+> Evaluate every category. If a category is not applicable, state the reason instead of leaving it blank.
+
+| Category | Requirement / Not Applicable Reason | Target / Standard | Priority | Verification |
+| --- | --- | --- | --- | --- |
+| Performance | | | P0 | |
+| Security / Privacy | | | P0 | |
+| Accessibility | | | P1 | |
+| Compatibility | | | P1 | |
+| Availability / Recovery | | | P1 | |
+| Observability | | | P1 | |
+| Data Consistency | | | P1 | |
+| Deployment / Operations | | | P1 | |
 
 ## Success Criteria *(mandatory)*
 

package/package-source/docs/codex-harness-engineering/templates/package-assets/.specify/templates/tasks-template.md

@@ -3,9 +3,9 @@
 description: "Task list template for feature implementation"
 ---
 
-# Tasks: [FEATURE NAME]
-
-> ⚠️ **重要**: 每个任务必须严格按照对应的规格文档实现，完成后需检查一致性。任务需要有清晰可见的完成边界，不要把一个 story 压成单个巨型任务。
+# Tasks: [FEATURE NAME]
+
+> ⚠️ **重要**: 每个任务必须严格按照对应的规格文档实现，完成后需检查一致性。任务需要有清晰可见的完成边界，不要把一个 story 压成单个巨型任务。
 
 ---
 
@@ -16,14 +16,14 @@ description: "Task list template for feature implementation"
 | **spec.md** | 需求规格、用户故事、验收标准 | 当前目录 |
 | **plan.md** | 技术设计、项目结构、服务划分 | 当前目录 |
 | **data-model.md** | 数据库实体、表结构、字段映射 | 当前目录 |
-| **contracts/openapi.yaml** | OpenAPI 3.0 接口契约定义 | 当前目录 |
-| **quickstart.md** | 环境搭建、启动顺序、验证方法 | 当前目录 |
-| **research.md** | 技术调研、选型依据 | 当前目录 |
-| **acceptance-examples.md** | 需求验收示例和可观察 oracle | 当前目录 |
-| **requirements-testability-review.md** | 每条需求是否可测、是否被 blocker 阻塞 | 当前目录 |
-| **verify-matrix.md** | Requirement -> 测试层级 / 命令 / 证据映射 | 当前目录 |
-| **test-strategy.md** | 基线命令、affected tests 和阻塞失败规则 | 当前目录 |
-| **test-manifest.json** | 给 hook / analyze / verify 读取的测试机器镜像 | 当前目录 |
+| **contracts/openapi.yaml** | OpenAPI 3.0 接口契约定义 | 当前目录 |
+| **quickstart.md** | 环境搭建、启动顺序、验证方法 | 当前目录 |
+| **research.md** | 技术调研、选型依据 | 当前目录 |
+| **acceptance-examples.md** | 需求验收示例和可观察 oracle | 当前目录 |
+| **requirements-testability-review.md** | 每条需求是否可测、是否被 blocker 阻塞 | 当前目录 |
+| **verify-matrix.md** | Requirement -> 测试层级 / 命令 / 证据映射 | 当前目录 |
+| **test-strategy.md** | 基线命令、affected tests 和阻塞失败规则 | 当前目录 |
+| **test-manifest.json** | 给 hook / analyze / verify 读取的测试机器镜像 | 当前目录 |
 
 > **Note**: 并非所有项目都有上述全部文档，根据 FEATURE_DIR 实际内容填写。
 
@@ -35,30 +35,30 @@ description: "Task list template for feature implementation"
 |------|------|------|
 | ... | ... | ... |
 
-<!-- 根据 plan.md 提取技术栈信息填写此表 -->
-
----
-
-## 集成型 Story 拆分参考
-
-> 如果当前 feature 是 `integration` / `production`，或者故事依赖既定 OSS、外部系统、真实环境，请优先按下面的验收边界拆任务，而不是生成一个吞掉全部职责的大任务。
-
-| 推荐切片 | 典型内容 | 何时单独成任务 |
-|------|------|------|
-| 环境 / blocker 证据 | `TBD-*`、RBAC、endpoint、dashboard、webhook、环境可用性 | 只要还存在真实接入前置条件，就应单独成任务 |
-| contract projection / schema mapping | 字段映射、查询条件、响应结构、saved query / metadata 对齐 | 当外部接口与本地领域模型之间存在映射层 |
-| real connector / read-write path | `lib/connectors/*`、adapter、重试、鉴权、错误包装 | 只要有真实下游接入，就应单独成任务 |
-| bridge / policy / metadata | RBAC bridge、query policy、fields metadata、状态归一化 | 当中间层逻辑独立于 UI / API 时 |
-| BFF / API / 页面消费 | 上层聚合、接口、页面、状态、空态、错误态 | 在真实 connector 已就位后再单独成任务 |
-| 联调 transcript / 失败态证据 | smoke、integration、e2e、downstream、release note | 真实集成收尾时单独成任务 |
-
-> 如果一个任务同时覆盖上表中 3 类以上职责，默认说明粒度过粗，需要继续拆分。
-
----
-
-<!-- 
-  ============================================================================
-  IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
+<!-- 根据 plan.md 提取技术栈信息填写此表 -->
+
+---
+
+## 集成型 Story 拆分参考
+
+> 如果当前 feature 是 `integration` / `production`，或者故事依赖既定 OSS、外部系统、真实环境，请优先按下面的验收边界拆任务，而不是生成一个吞掉全部职责的大任务。
+
+| 推荐切片 | 典型内容 | 何时单独成任务 |
+|------|------|------|
+| 环境 / blocker 证据 | `TBD-*`、RBAC、endpoint、dashboard、webhook、环境可用性 | 只要还存在真实接入前置条件，就应单独成任务 |
+| contract projection / schema mapping | 字段映射、查询条件、响应结构、saved query / metadata 对齐 | 当外部接口与本地领域模型之间存在映射层 |
+| real connector / read-write path | `lib/connectors/*`、adapter、重试、鉴权、错误包装 | 只要有真实下游接入，就应单独成任务 |
+| bridge / policy / metadata | RBAC bridge、query policy、fields metadata、状态归一化 | 当中间层逻辑独立于 UI / API 时 |
+| BFF / API / 页面消费 | 上层聚合、接口、页面、状态、空态、错误态 | 在真实 connector 已就位后再单独成任务 |
+| 联调 transcript / 失败态证据 | smoke、integration、e2e、downstream、release note | 真实集成收尾时单独成任务 |
+
+> 如果一个任务同时覆盖上表中 3 类以上职责，默认说明粒度过粗，需要继续拆分。
+
+---
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
   
   The /speckit.tasks command MUST replace these with actual tasks based on:
   - User stories from spec.md (with their priorities P1, P2, P3...)
@@ -80,18 +80,18 @@ description: "Task list template for feature implementation"
 - [ ] **T001 创建项目结构** <!-- id: 11 -->
   - 📋 **规格参考**: plan.md → Project Structure
   - _Requirements: FR-XXX_
-  - ✅ **验收标准**: 项目编译通过
-  - 📁 **创建文件**: `path/to/file`
-  - 🧪 **测试文件**: `TEST-GAP: 初始化任务无测试文件`
-  - 🟢 **GREEN 命令**:
-    - `git -c core.safecrlf=false diff --check`
-  - 📌 **受影响测试**:
-    - `TEST-GAP: 尚未生成项目测试命令`
-  - 🔍 **自检命令**:
-    - `git -c core.safecrlf=false diff --check`
-  - 📝 **执行内容**:
-    - 具体执行步骤 1
-    - 具体执行步骤 2
+  - ✅ **验收标准**: 项目编译通过
+  - 📁 **创建文件**: `path/to/file`
+  - 🧪 **测试文件**: `TEST-GAP: 初始化任务无测试文件`
+  - 🟢 **GREEN 命令**:
+    - `git -c core.safecrlf=false diff --check`
+  - 📌 **受影响测试**:
+    - `TEST-GAP: 尚未生成项目测试命令`
+  - 🔍 **自检命令**:
+    - `git -c core.safecrlf=false diff --check`
+  - 📝 **执行内容**:
+    - 具体执行步骤 1
+    - 具体执行步骤 2
 
 - [ ] **T002 [P] 创建基础设施** <!-- id: 12 -->
   - 📋 **规格参考**: quickstart.md → 启动基础设施

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

@@ -0,0 +1,19 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放会镜像到目标项目 `.agents/`、根目录安装脚本或附带文档面的打包资产。
+
+## 结构索引
+
+- `root/`：安装入口、根级脚本和包说明。
+- `rules/`：镜像到 package-assets 的 rules。
+- `docs/`：镜像文档。
+- `scripts/`：随包分发的脚本。
+- `skills/`：会复制到目标项目 `.agents/skills/` 的能力包。
+- `workflows/`：会复制到目标项目 `.agents/workflows/` 的流程资产。
+
+## 修改规则
+
+- 改这里要先判断是否同时需要改 `templates/` canonical 或当前仓库活跃副本。
+- package-assets 是镜像面，不应该成为唯一 canonical，除非文件只存在这里。

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

@@ -0,0 +1,25 @@
+# AGENTS.md
+
+## 作用范围
+
+- 本文件适用于 `docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/`。
+- 进入子目录后，继续读取该子目录自己的 `AGENTS.md`。
+
+## 目录作用
+
+- 这里是 `docs/codex-harness-engineering/*` 的 package-assets 文档镜像层。
+- 主要用于随安装包或镜像分发附带说明文档，不是默认第一 canonical。
+
+## 结构索引
+
+- 根目录 `*.md`：工程说明、使用文档、模式说明和方法论文档的镜像。
+- `examples/`：示例工程镜像。
+- `templates/`：模板文档镜像，不是模板源本体。
+
+## 修改规则
+
+- 默认先改上游 canonical：
+  - 方法论文档：`docs/codex-harness-engineering/*`
+  - 模板源：`docs/codex-harness-engineering/templates/*`
+- 只有在确认当前文件只存在镜像层，或本次任务就是修复 package-assets 分发面时，才先改这里。
+- 不要把这层镜像误当成安装模板源。