@pzy560117/codex-harness 0.1.2 → 0.1.4

package/package-source/docs/codex-harness-engineering/templates/package-assets/workflows/speckit.plan.md

@@ -8,14 +8,14 @@ description: Execute the implementation planning workflow using the plan templat
 $ARGUMENTS
 ```
 
-You **MUST** consider the user input before proceeding (if not empty).
-
-## 语言要求
-
-- 与用户的阶段汇报、阻塞说明、结论汇总全部使用简体中文。
-- 实际写入仓库的 `plan.md`、`research.md`、`architecture.md`、`product-readiness.md`、`design-readiness.md`、`data-model.md`、`quickstart.md` 以及相关说明文档必须使用简体中文。
-- 即使模板原文是英文，实际落盘时也要把标题、说明、表格内容、占位文本改写成中文，但保持原有章节顺序。
-- 保留不能随意翻译的机器敏感标记与技术标识，例如 `[NEEDS CLARIFICATION]`、需求编号、路径、命令、协议名、库名、接口路径。
+You **MUST** consider the user input before proceeding (if not empty).
+
+## 语言要求
+
+- 与用户的阶段汇报、阻塞说明、结论汇总全部使用简体中文。
+- 实际写入仓库的 `plan.md`、`research.md`、`architecture.md`、`product-readiness.md`、`design-readiness.md`、`data-model.md`、`quickstart.md` 以及相关说明文档必须使用简体中文。
+- 即使模板原文是英文，实际落盘时也要把标题、说明、表格内容、占位文本改写成中文，但保持原有章节顺序。
+- 保留不能随意翻译的机器敏感标记与技术标识，例如 `[NEEDS CLARIFICATION]`、需求编号、路径、命令、协议名、库名、接口路径。
 
 ## Outline
 
@@ -23,25 +23,25 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 2. **Load context**: Read FEATURE_SPEC and `.agents/.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
 
-3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
-   - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
-   - Fill Delivery Mode Gate and confirm it matches `spec.md`
-   - Fill OSS Reuse Matrix for every requirement/capability that depends on a predefined OSS stack, existing platform, or third-party system
-   - Fill Integration Blockers & Evidence with machine-readable `TBD-*` rows and statuses
-   - Fill Connector & Adapter Strategy, including sample-vs-real adapter separation
-   - Fill Requirement Completion Gates and Verification Layers
-   - Generate testing left-shift truth sources: `acceptance-examples.md`, `requirements-testability-review.md`, `verify-matrix.md`, `test-strategy.md`, and `test-manifest.json`
-   - Fill Truth Sources table
-   - Fill Product & Design Readiness gate table
-   - Fill Constitution Check section from constitution
-   - Evaluate gates (ERROR if violations unjustified)
-   - Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
-   - Phase 1: Generate architecture.md and verify module boundaries, data flow, integration points, irreversible decisions, and rule impact
-   - Phase 2: Generate product-readiness.md and verify product truth sources, including requirement-interface mapping and difficulty research
-   - Phase 3: Generate testing truth sources and machine-readable `test-manifest.json`
-   - Phase 4: Generate design-readiness.md and verify design-to-code truth sources, including AI image generation/review and image-to-frontend spec for UI work
-   - Phase 5: Generate data-model.md, contracts/, quickstart.md
-   - Phase 6: Update project rule files and agent context so downstream tasks consume current rules
+3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
+   - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
+   - Fill Delivery Mode Gate and confirm it matches `spec.md`
+   - Fill OSS Reuse Matrix for every requirement/capability that depends on a predefined OSS stack, existing platform, or third-party system
+   - Fill Integration Blockers & Evidence with machine-readable `TBD-*` rows and statuses
+   - Fill Connector & Adapter Strategy, including sample-vs-real adapter separation
+   - Fill Requirement Completion Gates and Verification Layers
+   - Generate testing left-shift truth sources: `acceptance-examples.md`, `requirements-testability-review.md`, `verify-matrix.md`, `test-strategy.md`, and `test-manifest.json`
+   - Fill Truth Sources table
+   - Fill Product & Design Readiness gate table
+   - Fill Constitution Check section from constitution
+   - Evaluate gates (ERROR if violations unjustified)
+   - Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
+   - Phase 1: Generate architecture.md and verify module boundaries, data flow, integration points, irreversible decisions, and rule impact
+   - Phase 2: Generate product-readiness.md and verify product truth sources, including requirement-interface mapping and difficulty research
+   - Phase 3: Generate testing truth sources and machine-readable `test-manifest.json`
+   - Phase 4: Generate design-readiness.md and verify design-to-code truth sources, including AI image generation/review and image-to-frontend spec for UI work
+   - Phase 5: Generate data-model.md, contracts/, quickstart.md
+   - Phase 6: Update project rule files and agent context so downstream tasks consume current rules
    - Re-evaluate Constitution Check post-design
 
 4. **Stop and report**: Command ends after planning artifacts are generated. Report branch, IMPL_PLAN path, readiness status, and generated artifacts.
@@ -50,12 +50,12 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ### Phase 0: Outline & Research
 
-1. **Extract unknowns from Technical Context** above:
-   - For each NEEDS CLARIFICATION → research task
-   - For each dependency → best practices task
-   - For each integration → patterns task
-   - For each predefined OSS / external system → reuse-vs-build task
-   - For each missing environment / endpoint / RBAC / dashboard / panel / webhook prerequisite → blocker evidence task
+1. **Extract unknowns from Technical Context** above:
+   - For each NEEDS CLARIFICATION → research task
+   - For each dependency → best practices task
+   - For each integration → patterns task
+   - For each predefined OSS / external system → reuse-vs-build task
+   - For each missing environment / endpoint / RBAC / dashboard / panel / webhook prerequisite → blocker evidence task
 
 2. **Generate and dispatch research agents**:
 
@@ -73,28 +73,29 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 **Output**: research.md with all NEEDS CLARIFICATION resolved
 
-### Phase 1: Architecture
-
-**Prerequisites:** `research.md` complete
-
-1. Generate `architecture.md` from confirmed spec, existing codebase patterns, and best practices:
-   - Module boundaries and ownership
-   - Data flow and integration points
-   - Connector boundaries and interface-to-adapter layering
-   - Real adapter vs sample/mock adapter separation
-   - Irreversible or expensive decisions
-   - Concurrency, migration, contract, and coupling risks
-   - Smallest defensible architecture and rejected alternatives
-
-2. Verify architecture-to-rule impact:
-   - Which project rules become stale after this architecture
-   - Which `AGENTS.md`, `docs/harness/*`, `docs/context/*` entries must be updated
-
-**Output**: `architecture.md`
-
-### Phase 2: Product Readiness
-
-**Prerequisites:** `architecture.md` complete
+### Phase 1: Architecture
+
+**Prerequisites:** `research.md` complete
+
+1. Generate `architecture.md` from confirmed spec, existing codebase patterns, and best practices:
+   - Module boundaries and ownership
+   - Data flow and integration points
+   - Connector boundaries and interface-to-adapter layering
+   - Real adapter vs sample/mock adapter separation
+   - Irreversible or expensive decisions
+   - Concurrency, migration, contract, and coupling risks
+   - Smallest defensible architecture and rejected alternatives
+
+2. Verify architecture-to-rule impact:
+   - Which project rules become stale after this architecture
+   - Which `AGENTS.md`, `docs/harness/*`, `docs/context/*` entries must be updated
+   - If this is a thin install project and `docs/harness/*` is absent from the project root, resolve those files under `packageRoot` from `.codex-harness/state/config.json`
+
+**Output**: `architecture.md`
+
+### Phase 2: Product Readiness
+
+**Prerequisites:** `architecture.md` complete
 
 1. Verify or generate product artifacts:
    - `docs/product/prd-lite.md`
@@ -104,54 +105,54 @@ You **MUST** consider the user input before proceeding (if not empty).
    - `docs/product/requirement-interface-matrix.md`
    - `docs/product/difficulty-research.md`
 
-2. Check required product coverage:
-   - Goals and non-goals
-   - Scope boundary
-   - Delivery mode and prototype/integration boundary
-   - Roles and permissions
-   - Page inventory
-   - Requirement-to-interface traceability for every P0/P1 requirement
+2. Check required product coverage:
+   - Goals and non-goals
+   - Scope boundary
+   - Delivery mode and prototype/integration boundary
+   - Roles and permissions
+   - Page inventory
+   - Requirement-to-interface traceability for every P0/P1 requirement
    - Upfront difficulty research for all high-risk unknowns
    - Required states
    - Measurable acceptance criteria
 
-**Output**: product-readiness.md
-
-### Phase 3: Testing Readiness
-
-**Prerequisites:** Product readiness complete
-
-1. Generate or verify `acceptance-examples.md`:
-   - Map every P0/P1 requirement to at least one scenario ID such as `AE-001`
-   - Include Given, When, Then, negative or edge case, observable oracle, and evidence path
-   - Do not use vague pass criteria such as "looks normal"
-
-2. Generate or verify `requirements-testability-review.md`:
-   - Mark every requirement as `Ready`, `Blocked`, `Needs Clarification`, or `Prototype Only`
-   - Record missing endpoint, RBAC, credential, dashboard/panel ID, webhook target, fixture, environment, or downstream evidence as a blocker
-   - For `integration` / `production`, keep related formal `FR-*` blocked while a linked blocker remains open
-
-3. Generate or verify `verify-matrix.md`:
-   - Map requirement IDs to acceptance examples, required test layers, test files, commands, evidence paths, and status
-   - Mark missing test files or commands as `TEST-GAP` instead of leaving cells blank
-   - Ensure `integration` / `production` requirements are not covered by unit tests alone
-
-4. Generate or verify `test-strategy.md`:
-   - Detect stack and list baseline command candidates
-   - Define affected-test selection strategy
-   - Define blocking failure rules and evidence directory
-
-5. Generate or verify `test-manifest.json`:
-   - Mirror delivery mode, baseline commands, requirement testability, layers, files, commands, evidence paths, blockers, and gaps
-   - Keep the JSON valid and minimal because stop hooks and verify workflows read it
-
-**Output**: `acceptance-examples.md`, `requirements-testability-review.md`, `verify-matrix.md`, `test-strategy.md`, `test-manifest.json`
-
-### Phase 4: Design Readiness
-
-**Prerequisites:** Product and testing readiness complete
-
-1. Verify or generate design artifacts:
+**Output**: product-readiness.md
+
+### Phase 3: Testing Readiness
+
+**Prerequisites:** Product readiness complete
+
+1. Generate or verify `acceptance-examples.md`:
+   - Map every P0/P1 requirement to at least one scenario ID such as `AE-001`
+   - Include Given, When, Then, negative or edge case, observable oracle, and evidence path
+   - Do not use vague pass criteria such as "looks normal"
+
+2. Generate or verify `requirements-testability-review.md`:
+   - Mark every requirement as `Ready`, `Blocked`, `Needs Clarification`, or `Prototype Only`
+   - Record missing endpoint, RBAC, credential, dashboard/panel ID, webhook target, fixture, environment, or downstream evidence as a blocker
+   - For `integration` / `production`, keep related formal `FR-*` blocked while a linked blocker remains open
+
+3. Generate or verify `verify-matrix.md`:
+   - Map requirement IDs to acceptance examples, required test layers, test files, commands, evidence paths, and status
+   - Mark missing test files or commands as `TEST-GAP` instead of leaving cells blank
+   - Ensure `integration` / `production` requirements are not covered by unit tests alone
+
+4. Generate or verify `test-strategy.md`:
+   - Detect stack and list baseline command candidates
+   - Define affected-test selection strategy
+   - Define blocking failure rules and evidence directory
+
+5. Generate or verify `test-manifest.json`:
+   - Mirror delivery mode, baseline commands, requirement testability, layers, files, commands, evidence paths, blockers, and gaps
+   - Keep the JSON valid and minimal because stop hooks and verify workflows read it
+
+**Output**: `acceptance-examples.md`, `requirements-testability-review.md`, `verify-matrix.md`, `test-strategy.md`, `test-manifest.json`
+
+### Phase 4: Design Readiness
+
+**Prerequisites:** Product and testing readiness complete
+
+1. Verify or generate design artifacts:
    - `docs/design/design-brief.md`
    - `docs/design/component-map.md`
    - `docs/design/screen-states.md`
@@ -170,52 +171,54 @@ You **MUST** consider the user input before proceeding (if not empty).
    - CSS/token requirements for AI image generation
    - Generated UI images reviewed against requirements and states
    - Approved images translated into frontend implementation specs
-
-**Output**: design-readiness.md
-
-### Phase 5: Data & Contracts
-
-**Prerequisites:** Product, testing, and design readiness complete
-
-1. **Extract entities from feature spec** → `data-model.md`:
+
+**Output**: design-readiness.md
+
+### Phase 5: Data & Contracts
+
+**Prerequisites:** Product, testing, and design readiness complete
+
+1. **Extract entities from feature spec** → `data-model.md`:
    - Entity name, fields, relationships
    - Validation rules from requirements
    - State transitions if applicable
 
-2. **Generate API contracts** from functional requirements:
-   - For each user action → endpoint
-   - Use standard REST/GraphQL patterns
-   - Output OpenAPI/GraphQL schema to `/contracts/`
-3. **Resolve integration blockers**:
-   - Verify every `TBD-*` row has an evidence path
-   - For `integration` / `production` work, unresolved blockers must keep related requirements in planned/blocked state
-   - Record environment smoke, downstream connectivity, and failure-path evidence locations in `quickstart.md` or companion notes
-
-### Phase 6: Rules & Context Sync
-
-**Prerequisites:** `architecture.md`, product readiness, testing readiness, and design readiness complete
-
-1. Update project rule files affected by the final spec and architecture:
-   - Project root `AGENTS.md`
-   - `docs/harness/*` long-lived workflow/rule files
-   - `docs/context/*` architecture/dev-plan context files when present
-
-2. Remove stale assumptions so downstream tasks do not inherit outdated rules.
-
-3. **Agent context update**:
+2. **Generate API contracts** from functional requirements:
+   - For each user action → endpoint
+   - Use standard REST/GraphQL patterns
+   - Output OpenAPI/GraphQL schema to `/contracts/`
+3. **Resolve integration blockers**:
+   - Verify every `TBD-*` row has an evidence path
+   - For `integration` / `production` work, unresolved blockers must keep related requirements in planned/blocked state
+   - Record environment smoke, downstream connectivity, and failure-path evidence locations in `quickstart.md` or companion notes
+
+### Phase 6: Rules & Context Sync
+
+**Prerequisites:** `architecture.md`, product readiness, testing readiness, and design readiness complete
+
+1. Update project rule files affected by the final spec and architecture:
+   - Project root `AGENTS.md`
+   - `docs/harness/*` long-lived workflow/rule files
+   - `docs/context/*` architecture/dev-plan context files when present
+
+For thin install projects, treat the package-root copies of `docs/harness/*` as the source to inspect when the project root does not include those files.
+
+2. Remove stale assumptions so downstream tasks do not inherit outdated rules.
+
+3. **Agent context update**:
    - Run `.agents/.specify/scripts/powershell/update-agent-context.ps1 -AgentType gemini`
    - These scripts detect which AI agent is in use
    - Update the appropriate agent-specific context file
    - Add only new technology from current plan
    - Preserve manual additions between markers
 
-**Output**: updated project rules, data-model.md, /contracts/*, quickstart.md, agent-specific file
-
-## Key rules
+**Output**: updated project rules, data-model.md, /contracts/*, quickstart.md, agent-specific file
 
-- Use absolute paths
-- ERROR on gate failures or unresolved clarifications
-- Do not replace a real integration requirement with local mock/sample implementation unless the user explicitly accepts downgrade and the plan records formal FRs as still incomplete
+## Key rules
+
+- Use absolute paths
+- ERROR on gate failures or unresolved clarifications
+- Do not replace a real integration requirement with local mock/sample implementation unless the user explicitly accepts downgrade and the plan records formal FRs as still incomplete
 
 ## Next Steps
 

package/package-source/docs/codex-harness-engineering/templates/package-assets/workflows/speckit.specify.md

@@ -8,14 +8,14 @@ description: Create or update the feature specification from a natural language
 $ARGUMENTS
 ```
 
-You **MUST** consider the user input before proceeding (if not empty).
-
-## 语言要求
-
-- 与用户的交互、澄清问题、推荐选项、完成汇报全部使用简体中文。
-- 实际写入仓库的 `spec.md` 及相关检查清单内容必须使用简体中文。
-- 即使模板原文是英文，实际落盘时也要把标题、说明、表格内容、占位文本改写成中文，但保持原有章节顺序。
-- 保留不能随意翻译的机器敏感标记与技术标识，例如 `[NEEDS CLARIFICATION]`、`FR-001`、`NFR-001`、`SC-001`、路径、命令、协议名、库名、接口路径。
+You **MUST** consider the user input before proceeding (if not empty).
+
+## 语言要求
+
+- 与用户的交互、澄清问题、推荐选项、完成汇报全部使用简体中文。
+- 实际写入仓库的 `spec.md` 及相关检查清单内容必须使用简体中文。
+- 即使模板原文是英文，实际落盘时也要把标题、说明、表格内容、占位文本改写成中文，但保持原有章节顺序。
+- 保留不能随意翻译的机器敏感标记与技术标识，例如 `[NEEDS CLARIFICATION]`、`FR-001`、`NFR-001`、`SC-001`、路径、命令、协议名、库名、接口路径。
 
 ## Outline
 
@@ -73,84 +73,84 @@ Given that feature description, do this:
 
     1. Parse user description from Input
        If empty: ERROR "No feature description provided"
-    2. Extract key concepts from description
-       Identify: actors, actions, data, constraints, pages/views, states, permissions, success metrics
-    3. Before writing FRs, lock the delivery posture:
-       - Determine whether the request is `prototype`, `spike`, `integration`, or `production`
-       - If the user mentions a predefined OSS stack, existing platform, dashboard system, metrics stack, webhook target, or real external environment, default to `integration` unless the user explicitly approves prototype downgrade
-       - If delivery posture is not clear, spend one of the allowed clarifications on this decision first
-    4. Run the requirement enrichment gate before drafting FRs:
-       - Build a three-column inventory: `Explicit`, `Inferred`, and `Decision Required`
-       - `Explicit`: preserve requirements directly stated by the user
-       - `Inferred`: add details that can be safely derived from domain norms, engineering best practices, official documentation, existing project constraints, or local code conventions
-       - `Decision Required`: mark choices that affect business scope, pricing, compliance, brand promise, real external dependencies, or the primary UX path
-       - For every P0/P1 candidate requirement, fill or block: actor, trigger, success result, failure result, boundary case, permission behavior, required data, observable oracle, evidence path, and release impact
-       - For UI-facing work, automatically add default, loading, empty, error, permission_denied, disabled, long_content, and mobile state requirements, or write why a state is not applicable
-       - For API/backend work, automatically add validation, error code, permission, idempotency or side-effect/no-side-effect, lifecycle/state-machine, audit, and observability requirements when relevant
-       - For all production-like work, evaluate performance, security, privacy, accessibility, compatibility, availability, observability, data consistency, backup/recovery, deployment, and operations constraints; write "not applicable because ..." instead of leaving blanks
-       - Write the enrichment result to `specs/<feature>/requirements-enrichment.md`
-       - If any P0/P1 item lacks acceptance criteria, test data, oracle, evidence path, or executable verification, mark it `Needs Clarification` or `Blocked`; do not mark it `Ready`
-    5. For unclear aspects:
-       - Make informed guesses based on context and industry standards
-       - Only mark with [NEEDS CLARIFICATION: specific question] if:
-         - The choice significantly impacts feature scope or user experience
-         - Multiple reasonable interpretations exist with different implications
-         - No reasonable default exists
+    2. Extract key concepts from description
+       Identify: actors, actions, data, constraints, pages/views, states, permissions, success metrics
+    3. Before writing FRs, lock the delivery posture:
+       - Determine whether the request is `prototype`, `spike`, `integration`, or `production`
+       - If the user mentions a predefined OSS stack, existing platform, dashboard system, metrics stack, webhook target, or real external environment, default to `integration` unless the user explicitly approves prototype downgrade
+       - If delivery posture is not clear, spend one of the allowed clarifications on this decision first
+    4. Run the requirement enrichment gate before drafting FRs:
+       - Build a three-column inventory: `Explicit`, `Inferred`, and `Decision Required`
+       - `Explicit`: preserve requirements directly stated by the user
+       - `Inferred`: add details that can be safely derived from domain norms, engineering best practices, official documentation, existing project constraints, or local code conventions
+       - `Decision Required`: mark choices that affect business scope, pricing, compliance, brand promise, real external dependencies, or the primary UX path
+       - For every P0/P1 candidate requirement, fill or block: actor, trigger, success result, failure result, boundary case, permission behavior, required data, observable oracle, evidence path, and release impact
+       - For UI-facing work, automatically add default, loading, empty, error, permission_denied, disabled, long_content, and mobile state requirements, or write why a state is not applicable
+       - For API/backend work, automatically add validation, error code, permission, idempotency or side-effect/no-side-effect, lifecycle/state-machine, audit, and observability requirements when relevant
+       - For all production-like work, evaluate performance, security, privacy, accessibility, compatibility, availability, observability, data consistency, backup/recovery, deployment, and operations constraints; write "not applicable because ..." instead of leaving blanks
+       - Write the enrichment result to `specs/<feature>/requirements-enrichment.md`
+       - If any P0/P1 item lacks acceptance criteria, test data, oracle, evidence path, or executable verification, mark it `Needs Clarification` or `Blocked`; do not mark it `Ready`
+    5. For unclear aspects:
+       - Make informed guesses based on context and industry standards
+       - Only mark with [NEEDS CLARIFICATION: specific question] if:
+         - The choice significantly impacts feature scope or user experience
+         - Multiple reasonable interpretations exist with different implications
+         - No reasonable default exists
        - **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total**
        - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
-    6. Fill Overview, goals, non-goals, scope boundary, and delivery/integration boundary
-       Non-goals are mandatory; write explicit exclusions rather than leaving them implicit
-    7. Fill User Scenarios & Testing section
-       If no clear user flow: ERROR "Cannot determine user scenarios"
-    8. Fill Testability & Acceptance Evidence
-       - For every P0/P1 `FR-*` and relevant `NFR-*`, define:
-         - observable result
-         - positive Given/When/Then example
-         - negative or edge example
-         - required test data
-         - evidence path
-         - `Ready` / `Needs Clarification` / `Blocked` / `Prototype Only`
-       - If a real integration depends on missing environment, endpoint, RBAC, dashboard, webhook, fixture, credential, or downstream system, create a `TBD-TEST-*` or linked `TBD-*` precondition instead of treating the requirement as testable
-       - If the work is `prototype` / `spike`, record demo evidence boundaries and do not imply that formal `FR-*` will close
-    9. Fill Pages, States & Permissions for UI-facing features
-       Required states: default, empty, loading, error, permission_denied, disabled, long_content, mobile
-       If a state is not applicable, write why
-    10. Generate Functional Requirements
-       Each requirement must be testable
-       Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
-       If the current work is only `prototype` or `spike`, do not use demo-only deliverables to imply formal `FR-*` closure; put them in the optional `PROTO-*` / `SPIKE-*` section instead
-    11. Generate business rules, data dictionary, non-functional requirements, and external dependency preconditions when relevant
-    12. Define Success Criteria
-       Create measurable, technology-agnostic outcomes
-       Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion)
-       Each criterion must be verifiable without implementation details
-    13. Identify Key Entities (if data involved)
-    14. Fill Risks, Assumptions & Open Questions
-    15. Map every P0/P1 requirement to interfaces:
-       - Each requirement must reference page/view IDs, UI states, fields, operations, APIs, and acceptance criteria
-       - Each page/view/modal/drawer must have a requirement source
-       - If a requirement has no interface/API/test mapping, mark it as a gap or BLOCKED
-    16. Identify upfront difficulties:
-       - Research-heavy implementation, UI, data, integration, performance, permission, or interaction issues
-       - For each high-risk difficulty, create a research item with alternatives and validation approach
-       - Do not defer core feasibility research to implementation
-    17. If integrations exist, enumerate the external systems, existing OSS stack, and any known `TBD-*` blocker placeholders that the plan must resolve before implementation
-    18. Map the spec to product and testing artifacts:
-       - `docs/product/prd-lite.md`
-       - `docs/product/page-inventory.md`
-       - `docs/product/state-matrix.yaml`
-       - `docs/product/acceptance-criteria.md`
-       - `docs/product/requirement-interface-matrix.md`
-       - `docs/product/difficulty-research.md`
-       - `specs/<feature>/requirements-enrichment.md`
-       - `specs/<feature>/acceptance-examples.md`
-       - `specs/<feature>/requirements-testability-review.md`
-       - `specs/<feature>/verify-matrix.md`
-       - `specs/<feature>/test-strategy.md`
-       - `specs/<feature>/test-manifest.json`
-    19. Return: SUCCESS (spec ready for clarification or planning)
-
-5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order. The final written headings and prose must be in Simplified Chinese.
+    6. Fill Overview, goals, non-goals, scope boundary, and delivery/integration boundary
+       Non-goals are mandatory; write explicit exclusions rather than leaving them implicit
+    7. Fill User Scenarios & Testing section
+       If no clear user flow: ERROR "Cannot determine user scenarios"
+    8. Fill Testability & Acceptance Evidence
+       - For every P0/P1 `FR-*` and relevant `NFR-*`, define:
+         - observable result
+         - positive Given/When/Then example
+         - negative or edge example
+         - required test data
+         - evidence path
+         - `Ready` / `Needs Clarification` / `Blocked` / `Prototype Only`
+       - If a real integration depends on missing environment, endpoint, RBAC, dashboard, webhook, fixture, credential, or downstream system, create a `TBD-TEST-*` or linked `TBD-*` precondition instead of treating the requirement as testable
+       - If the work is `prototype` / `spike`, record demo evidence boundaries and do not imply that formal `FR-*` will close
+    9. Fill Pages, States & Permissions for UI-facing features
+       Required states: default, empty, loading, error, permission_denied, disabled, long_content, mobile
+       If a state is not applicable, write why
+    10. Generate Functional Requirements
+       Each requirement must be testable
+       Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
+       If the current work is only `prototype` or `spike`, do not use demo-only deliverables to imply formal `FR-*` closure; put them in the optional `PROTO-*` / `SPIKE-*` section instead
+    11. Generate business rules, data dictionary, non-functional requirements, and external dependency preconditions when relevant
+    12. Define Success Criteria
+       Create measurable, technology-agnostic outcomes
+       Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion)
+       Each criterion must be verifiable without implementation details
+    13. Identify Key Entities (if data involved)
+    14. Fill Risks, Assumptions & Open Questions
+    15. Map every P0/P1 requirement to interfaces:
+       - Each requirement must reference page/view IDs, UI states, fields, operations, APIs, and acceptance criteria
+       - Each page/view/modal/drawer must have a requirement source
+       - If a requirement has no interface/API/test mapping, mark it as a gap or BLOCKED
+    16. Identify upfront difficulties:
+       - Research-heavy implementation, UI, data, integration, performance, permission, or interaction issues
+       - For each high-risk difficulty, create a research item with alternatives and validation approach
+       - Do not defer core feasibility research to implementation
+    17. If integrations exist, enumerate the external systems, existing OSS stack, and any known `TBD-*` blocker placeholders that the plan must resolve before implementation
+    18. Map the spec to product and testing artifacts:
+       - `docs/product/prd-lite.md`
+       - `docs/product/page-inventory.md`
+       - `docs/product/state-matrix.yaml`
+       - `docs/product/acceptance-criteria.md`
+       - `docs/product/requirement-interface-matrix.md`
+       - `docs/product/difficulty-research.md`
+       - `specs/<feature>/requirements-enrichment.md`
+       - `specs/<feature>/acceptance-examples.md`
+       - `specs/<feature>/requirements-testability-review.md`
+       - `specs/<feature>/verify-matrix.md`
+       - `specs/<feature>/test-strategy.md`
+       - `specs/<feature>/test-manifest.json`
+    19. Return: SUCCESS (spec ready for clarification or planning)
+
+5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order. The final written headings and prose must be in Simplified Chinese.
 
 6. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
 
@@ -163,22 +163,22 @@ Given that feature description, do this:
       - Scope boundary is clear
       - User stories are independently testable
       - Page inventory and state coverage are complete for UI-facing work
-      - Requirement-to-interface mapping covers every P0/P1 requirement
-      - Every interface element has a requirement source
-      - Delivery mode is explicit and matches the intended acceptance boundary
-      - Requirement enrichment has separated `Explicit`, `Inferred`, and `Decision Required` items
-      - Automatically inferred requirements are recorded as assumptions with validation methods and impact if false
-      - P0/P1 requirements are not marked `Ready` when acceptance criteria, test data, oracle, evidence path, or executable verification are missing
-      - Non-functional requirements cover performance, security/privacy, accessibility, compatibility, availability, observability, data consistency, deployment/operations, or state why a category is not applicable
-      - Features mentioning existing OSS/external systems do not silently downgrade to local mock behavior
-      - Prototype / spike deliverables are not masquerading as completed formal `FR-*`
-      - High-risk difficulties have research items before implementation
-      - Permission differences are represented
-      - Functional requirements are testable
-      - P0/P1 requirements have observable results, positive examples, negative or edge examples, required test data, and evidence paths
-      - Testability status is not `Ready` when required external evidence is missing
-      - Prototype / spike evidence does not close formal integration or production requirements
-      - Acceptance criteria are measurable
+      - Requirement-to-interface mapping covers every P0/P1 requirement
+      - Every interface element has a requirement source
+      - Delivery mode is explicit and matches the intended acceptance boundary
+      - Requirement enrichment has separated `Explicit`, `Inferred`, and `Decision Required` items
+      - Automatically inferred requirements are recorded as assumptions with validation methods and impact if false
+      - P0/P1 requirements are not marked `Ready` when acceptance criteria, test data, oracle, evidence path, or executable verification are missing
+      - Non-functional requirements cover performance, security/privacy, accessibility, compatibility, availability, observability, data consistency, deployment/operations, or state why a category is not applicable
+      - Features mentioning existing OSS/external systems do not silently downgrade to local mock behavior
+      - Prototype / spike deliverables are not masquerading as completed formal `FR-*`
+      - High-risk difficulties have research items before implementation
+      - Permission differences are represented
+      - Functional requirements are testable
+      - P0/P1 requirements have observable results, positive examples, negative or edge examples, required test data, and evidence paths
+      - Testability status is not `Ready` when required external evidence is missing
+      - Prototype / spike evidence does not close formal integration or production requirements
+      - Acceptance criteria are measurable
       - Risks, assumptions, and open questions are documented
 
    d. **Handle Validation Results**: