@pzy560117/codex-harness 0.1.0 → 0.1.2

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

@@ -0,0 +1,307 @@
+# Feature Specification: [FEATURE NAME]
+
+**Feature Branch**: `[###-feature-name]`  
+**Created**: [DATE]  
+**Status**: Draft  
+**Input**: User description: "$ARGUMENTS"
+
+## Overview *(mandatory)*
+
+### Problem Statement
+
+[Describe the business/user problem this feature solves. Avoid implementation details.]
+
+### Goals
+
+- **G-001**: [Specific measurable goal]
+- **G-002**: [Specific measurable goal]
+
+### Non-Goals
+
+- **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)*
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+  
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - [Brief Title] (Priority: P1)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 2 - [Brief Title] (Priority: P2)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 3 - [Brief Title] (Priority: P3)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+[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.
+-->
+
+- 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 |
+| --- | --- | --- | --- | --- | --- | --- |
+| page-001 | | | | | default, empty, loading, error | FR-001 |
+
+### State Coverage
+
+| Page ID | default | empty | loading | error | permission_denied | disabled | long_content | mobile |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| page-001 | Required | Required | Required | Required | Required/NA | Required/NA | Required/NA | Required/NA |
+
+### Permission Matrix
+
+| Action | Role A | Role B | Role C | Notes |
+| --- | --- | --- | --- | --- |
+| 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"]  
+- **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)*
+
+- **[Entity 1]**: [What it represents, key attributes without implementation]
+- **[Entity 2]**: [What it represents, relationships to other entities]
+
+### Data Dictionary *(include if fields affect UI, APIs, or persistence)*
+
+| Field | Meaning | Type | Source | Required | Allowed Values / Range | Boundary Rule |
+| --- | --- | --- | --- | --- | --- | --- |
+| | | | | | | |
+
+## 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)*
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
+- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
+- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
+- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]
+
+## Risks, Assumptions & Open Questions *(mandatory)*
+
+### Risks
+
+| Risk ID | Risk | Impact | Probability | Mitigation | Owner |
+| --- | --- | --- | --- | --- | --- |
+| R-001 | | High/Medium/Low | High/Medium/Low | | |
+
+### Assumptions
+
+| Assumption ID | Assumption | Validation Method | Impact If False |
+| --- | --- | --- | --- |
+| A-001 | | | |
+
+### Open Questions
+
+| Question ID | Question | Owner | Due Date | Status |
+| --- | --- | --- | --- | --- |
+| Q-001 | | | | Open |
+
+## Product Artifact Mapping *(mandatory)*
+
+| Artifact | Target Path | Purpose |
+| --- | --- | --- |
+| PRD-Lite | `docs/product/prd-lite.md` | Product truth source |
+| Page Inventory | `docs/product/page-inventory.md` | Page and view scope |
+| State Matrix | `docs/product/state-matrix.yaml` | UI state coverage |
+| Acceptance Criteria | `docs/product/acceptance-criteria.md` | Verification entry point |
+| Requirement Interface Matrix | `docs/product/requirement-interface-matrix.md` | Requirement-to-page/state/API/test traceability |
+| Difficulty Research | `docs/product/difficulty-research.md` | Upfront research for hard problems and risks |

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

@@ -0,0 +1,244 @@
+---
+
+description: "Task list template for feature implementation"
+---
+
+# Tasks: [FEATURE NAME]
+
+> ⚠️ **重要**: 每个任务必须严格按照对应的规格文档实现，完成后需检查一致性。任务需要有清晰可见的完成边界，不要把一个 story 压成单个巨型任务。
+
+---
+
+## 📚 文档引用索引
+
+| 文档 | 用途 | 路径 |
+|------|------|------|
+| **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 读取的测试机器镜像 | 当前目录 |
+
+> **Note**: 并非所有项目都有上述全部文档，根据 FEATURE_DIR 实际内容填写。
+
+---
+
+## 🛠️ 技术栈速查
+
+| 层级 | 技术 | 版本 |
+|------|------|------|
+| ... | ... | ... |
+
+<!-- 根据 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...)
+  - Feature requirements from plan.md
+  - Entities from data-model.md
+  - Endpoints from contracts/
+  
+  Tasks MUST be organized by user story so each story can be:
+  - Implemented independently
+  - Tested independently
+  - Delivered as an MVP increment
+  
+  DO NOT keep these sample tasks in the generated tasks.md file.
+  ============================================================================
+-->
+
+## Phase 1: 项目初始化与基础设施 <!-- id: 10 -->
+
+- [ ] **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
+
+- [ ] **T002 [P] 创建基础设施** <!-- id: 12 -->
+  - 📋 **规格参考**: quickstart.md → 启动基础设施
+  - _Requirements: FR-XXX_
+  - ✅ **验收标准**: 基础设施启动成功
+  - 📁 **创建文件**: `path/to/file`
+
+---
+
+## Phase 2: [User Story Title] — US1 [Description] (Priority: P1) 🎯 MVP <!-- id: 20 -->
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+- [ ] **T003 [US1] 创建服务项目结构** <!-- id: 21 -->
+  - 📋 **规格参考**: plan.md → Phase 2
+  - _Requirements: FR-001~FR-005_
+  - 📁 **创建文件**:
+    - `src/main/java/.../Application.java`
+    - `src/main/resources/application.yml`
+
+- [ ] **T004 [US1] 创建数据库迁移** <!-- id: 22 -->
+  - 📋 **规格参考**: data-model.md → Entity
+  - _Requirements: FR-001_
+  - 📁 **创建文件**: `src/main/resources/db/migration/V1__create_table.sql`
+  - ✅ **字段检查**: id, name, ...
+
+- [ ] **T005 [US1] 创建实体和 Mapper** <!-- id: 23 -->
+  - 📋 **规格参考**: data-model.md → Entity, openapi.yaml → VO schema
+  - _Requirements: FR-001~FR-004_
+  - 📁 **创建文件**:
+    - `entity/Entity.java`
+    - `mapper/EntityMapper.java`
+    - `dto/CreateDTO.java`
+    - `vo/EntityVO.java`
+  - ✅ **一致性检查**: VO 字段与 openapi.yaml schema 完全一致
+
+- [ ] **T006 [US1] 实现 Service 业务逻辑** <!-- id: 24 -->
+  - 📋 **规格参考**: spec.md → FR-001~FR-005
+  - _Requirements: FR-001, FR-002, ..._
+  - 📁 **创建文件**: `service/Service.java`
+  - 📝 **方法清单**:
+    - `method1()`: 描述
+    - `method2()`: 描述
+
+- [ ] **T007 [US1] 实现 Controller REST 接口** <!-- id: 25 -->
+  - 📋 **规格参考**: openapi.yaml → /endpoint 系列接口
+  - _Requirements: FR-001~FR-005_
+  - 📁 **创建文件**: `controller/Controller.java`
+  - ✅ **接口清单**:
+    | 方法 | 路径 | 鉴权 |
+    |------|------|------|
+    | POST | `/endpoint` | ❌ |
+    | GET | `/endpoint/{id}` | ✅ |
+
+- [ ] **T008 [US1] 服务验证** <!-- id: 26 -->
+  - _Validates: US1 Scenario 1-4_
+  - ✅ **验证场景**:
+    - 场景 1 描述 → 预期结果
+    - 场景 2 描述 → 预期结果
+
+**Checkpoint**: US1 功能完整可用
+
+---
+
+## Phase 3: [User Story Title] — US2 [Description] (Priority: P1/P2) <!-- id: 30 -->
+
+**Goal**: [Brief description]
+
+**Independent Test**: [How to verify]
+
+- [ ] **T009 [US2] 创建服务项目结构** <!-- id: 31 -->
+  ...
+
+- [ ] **T010 [US2] 服务验证** <!-- id: 32 -->
+  ...
+
+**Checkpoint**: US2 功能完整可用
+
+---
+
+[Add more phases as needed, following the same pattern]
+
+---
+
+## Phase N: 联调验收与 Polish <!-- id: N0 -->
+
+**Purpose**: 全流程验证、文档完善、性能安全检查
+
+- [ ] **TXXX [P] 全流程 E2E 验证** <!-- id: N1 -->
+  - _Validates: US1-USn 全场景, SC-001~SC-XXX_
+  - ✅ **验证场景**: 完整用户流程
+
+- [ ] **TXXX [P] 性能与安全检查** <!-- id: N2 -->
+  - _Validates: NFR-001~NFR-XXX_
+  - ✅ API p95 < 500ms
+  - ✅ 密码加密存储
+  - ✅ SQL 注入/XSS 防护
+
+---
+
+## Dependencies & Execution Order
+
+### Phase 依赖
+
+```
+Phase 1 (基础设施) ──→ Phase 2 (US1)
+                   ──→ Phase 3 (US2)
+Phase 2 ─────────────→ Phase 4 (US3)
+All ─────────────────→ Phase N (联调)
+```
+
+### User Story 依赖
+
+| User Story | 依赖 | 所在 Phase |
+|-----------|------|-----------
+| US1 | Phase 1 基础设施 | Phase 2 |
+| US2 | Phase 1 | Phase 3 |
+| US3 | Phase 2 + Phase 3 | Phase 4 |
+
+### 并行机会
+
+- Phase 2 与 Phase 3 **可并行**（如无交叉依赖）
+- 每个 Phase 内标注 [P] 的任务可并行执行
+
+---
+
+## Implementation Strategy
+
+### MVP First（核心闭环优先）
+
+1. Phase 1: 基础设施搭建
+2. Phase 2: US1 → **验证**: 核心功能
+3. **STOP**: P1 完成，可进行演示
+
+### Incremental Delivery
+
+4. Phase 3: US2 → P2 功能
+5. Phase N: 全流程联调验收
+
+---
+
+## Notes
+
+- **[P]** 标记的任务可与同 Phase 内其他 [P] 任务并行
+- **[USn]** 标记关联到 spec.md 中的 User Story n
+- 每个 Phase 完成后执行 Checkpoint 验证
+- 每个任务使用 📋📁📝✅ 图标标注规格参考/文件/内容/验收标准
+- HTML 注释 `<!-- id: XX -->` 用于任务追踪

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

@@ -0,0 +1,98 @@
+# Architecture Constraints Packet
+
+本文档是当前 Codex Harness / agent 安装包改造的架构约束真相源。所有 `feature_impl`、安装器改造、doctor gate、manifest/lock 迁移和默认安装语义切换任务，都必须先满足本文件，再进入实现、Stage 1 Review 和发布验证。
+
+## 1. System Shape
+
+- `delivery_shape`: `cli` + `automation` + `package`
+- `runtime_model`: `command`
+- `deployment_unit`: `package`
+- `production_entrypoints`:
+  - `tools/install/install-agent.ps1`
+  - `docs/codex-harness-engineering/templates/package-assets/root/install-agent.ps1`
+  - `tools/harness/codex-loop.ps1`
+  - `docs/codex-harness-engineering/templates/runtime/codex-loop.ps1`
+  - `tools\harness\doctor.ps1`
+  - `tools\harness\verify.ps1`
+  - `refresh-agent-package.ps1`
+  - `tools/harness/tests/test-install-modes.ps1`
+
+当前项目不是 Web 应用、后端服务、数据库服务或 UI 工程；HTTP、UI route、DB migration、container deployment 均为 `not_applicable`。
+
+## 2. Public Interface Boundary
+
+- `public_interfaces`: `CLI`, `file format`, `package API`
+- `contract_source`: `docs/agent-package-redesign/target-layering-standard.md`, `docs/agent-package-redesign/migration-plan.md`, `docs/harness/install-manifest-governance.md`, `docs/harness/new-project-usage.md`, `task.json`
+- `interface_trace_rule`:
+  - 每个安装器公开入口必须能追踪到 `install-manifest.json`、lock/config 写入规则、doctor 检查和 smoke 测试。
+  - 每个 driver/runtime 行为变更必须能追踪到 `tools\harness\codex-loop.ps1`、`task.json`、trace 输出和验证命令。
+  - 每个 package surface 变更必须运行 `refresh-agent-package.ps1 -Surface all -Fix`，并用 `-CheckOnly` 证明 root、`agent/`、templates 和 ai-sync 元数据一致。
+
+## 3. Data Boundary
+
+- `persistence_boundary`: `filesystem`
+- `schema_or_migration_required`: `no`
+- `repository_policy`:
+  - 真实交付路径是 PowerShell 脚本对目标项目文件系统的受控读写，以及 JSON/Markdown manifest、lock、config、task 和 trace 文件。
+  - 测试可以使用临时目录 fixture，但不能把 fixture-only 行为冒充真实安装语义；所有安装语义必须通过 `tools/harness/tests/test-install-modes.ps1` 或等价 smoke 命令覆盖。
+  - JSON 文件必须通过 JSON parser 验证，不用字符串拼接冒充结构化写入。
+- `consistency_requirements`:
+  - `install-manifest.json`、`.codex-harness/locks/package.lock.json`、`.codex-harness/state/config.json`、用户级 package lock 和 ai-sync metadata 必须可审计。
+  - managed file 必须记录 hash；发现 drift 时默认阻断写入、升级或卸载。
+  - `-MigratePlan` 必须只读；迁移执行必须以 plan 分类为输入语义来源。
+
+## 4. Async And Worker Boundary
+
+- `async_required`: `no`
+- `scheduling_model`: `manual command`
+- `concurrency_control`: `single process`
+- `time_source`: `server time`
+
+`tools\harness\codex-loop.ps1 -RunUntilDone` 可以串行调度多个 `task.json` 任务，但每轮只处理一个依赖已满足且 `passes=false` 的任务。不得手工把未验证任务标记为 `passes=true`。
+
+## 5. Test Double Policy
+
+- `test_double_allowed_scope`: `unit_tests_only` and `temporary_install_fixtures`
+- `mock_as_acceptance_evidence`: `no`
+- `minimum_integration_evidence`:
+  - PowerShell parser 检查：root、agent、template runtime 脚本。
+  - JSON parse：`task.json`、`install-manifest.json`、schema、ai-sync metadata、project task template。
+  - Install smoke：旧 `-Mode full/project/vendor/user` 兼容路径，新 `-Scope user/project/vendor`，默认 thin 切换前后的目标路径。
+  - Doctor/manifest gate：`tools\harness\doctor.ps1`、`refresh-agent-package.ps1 -Surface all -CheckOnly`。
+  - 发布前完整验证：`tools\harness\verify.ps1`。
+
+## 6. Forbidden Implementations
+
+- 禁止把默认 thin project install 做成复制完整 `.agents/skills`、`.agents/workflows`、package docs 或 template source。
+- 禁止在未确认迁移计划时递归删除 `.agents/`、`docs/harness/`、`docs/testing/`、`docs/knowledge/` 或 `docs/requirement-prep-kit/`。
+- 禁止让 `-MigratePlan` 写文件、创建 lock 或删除目录。
+- 禁止绕过 `blocked-user-drift`、`unknown-legacy-file`、`manual-review` 分类直接写 lock 或删除文件。
+- 禁止把 `missing-vendor-file` 写入 `managedFiles`。
+- 禁止修改 `-Mode full/project/vendor/user` 兼容行为，除非任务明确进入默认切换阶段并保留显式 legacy/vendor 入口。
+- 禁止通过字符串拼接 shell 命令执行删除、移动或覆盖；Windows 文件操作必须使用 PowerShell 原生命令和 `-LiteralPath`。
+- 禁止只运行 `git diff --check` 就声明实现任务完成；必须运行任务声明的 smoke、doctor、refresh CheckOnly 或 verify。
+
+## 7. Architecture Fitness Checks
+
+最低可执行检查如下：
+
+```powershell
+powershell -NoProfile -Command "[scriptblock]::Create((Get-Content -Raw .\tools\harness\codex-loop.ps1)) | Out-Null; [scriptblock]::Create((Get-Content -Raw .\docs\codex-harness-engineering\templates\runtime\codex-loop.ps1)) | Out-Null; [scriptblock]::Create((Get-Content -Raw .\tools\install\install-agent.ps1)) | Out-Null; 'parser ok'"
+powershell -NoProfile -Command "Get-Content -Raw .\task.json | ConvertFrom-Json | Out-Null; Get-Content -Raw .\tools\harness\templates\project-task-template.json | ConvertFrom-Json | Out-Null; Get-Content -Raw .\install-manifest.json | ConvertFrom-Json | Out-Null; 'json ok'"
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\tests\test-install-modes.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\doctor.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\refresh-agent-package.ps1 -RepoRoot . -PackageRoot agent -Surface all -CheckOnly
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\verify.ps1
+git diff --check
+```
+
+文档或契约任务可按 `task.json.test_command` 缩小验证范围，但不能跳过对应的 package freshness 和 whitespace 检查。实现任务必须覆盖 install smoke、doctor 和相关 JSON/PowerShell parser 检查。
+
+## 8. Definition Of Done
+
+- 任务的 `architecture_constraints` 和 `forbidden_implementations` 与本文件一致，且没有冲突。
+- 新增或修改的公开 CLI 参数在文档、安装器、doctor/smoke 和 manifest/lock 语义中一致。
+- 当前仓库、package templates 和 ai-sync metadata 同步通过。
+- Stage 1 Review 能以本文件和任务 context files 作为 architecture truth source 给出 PASS。
+- Stage 2 Review 能看到对应测试、doctor、refresh CheckOnly 或 verify 证据。
+- 完成声明必须列出默认安装语义、兼容入口、迁移入口、验证命令和剩余风险。