architext 0.0.4 → 0.0.5

package/dist/templates/en/docs/prompts/plan.md

@@ -1,346 +1,241 @@
 <protocol_plan>
-  **Trigger**: `/archi.plan <ID> [context]`
-  **Goal**: Define Task Spec/UI/Plan through deep architecture interview.
+  **Trigger**: `/archi.plan <ID> [context]` | Auto-loaded by Workflow Dispatch on natural language trigger
+  **Goal**: Define task Spec/UI/Plan through deep architecture interview.
   **Input**:
-  - `<ID>` (required): An existing task ID from the Roadmap. Tasks must be created first via `/archi.scope` or `/archi.inherit`.
-  - `[context]` (optional): Known context for the task (e.g., requirement descriptions, references, constraints). When provided, serves as pre-loaded input for step_2 interview, reducing questions.
+  - `<ID>` (required): Existing task ID in Roadmap. Must create via `/archi.scope` or `/archi.inherit` first.
+  - `[context]` (optional): Known context for the task (e.g. requirement descriptions, references, constraints). When provided, serves as pre-input for step_2 interview, reducing questions.
 
 <constraints_cursor>
-    **Mode Lock**: This protocol MUST execute in **Agent Mode (Normal Mode)**. Prohibited from switching to Plan Mode or any read-only mode.
+    **Mode Lock**: This protocol must run in **Agent Mode (Normal Mode)**. Do not switch to Plan Mode or other read-only modes.
 </constraints_cursor>
 
 <meta>
     <style>Architectural, Exhaustive, Strict, Technology-Agnostic</style>
     <language>English</language>
     <principles>
-      1.  **Global First**: The birth of local tasks must be accompanied by updates to global indices (Map/Data/Dict).
-      2.  **AI-Native Perspective**: All option Pros/Cons written from AI Agent perspective. Focus: Context Locality, Type Safety, Boilerplate, Ambiguity.
+      1.  **Global First**: Local task birth must accompany global index (Map/Data/Dict) updates.
+      2.  **AI-Native Perspective**: All option Pros/Cons from AI Agent perspective. Focus: Context Locality, Type Safety, Boilerplate, Ambiguity.
       3.  **Flexible Interaction**: Options are heuristic suggestions; support multi-select, hybrid, or custom.
       4.  **Audit-Gated**: Only audited docs can be delivered.
+      5.  **IDE-Native First**: Leverage IDE native capabilities to drive execution rhythm; this protocol defines quality standards and checkpoints, not fight IDE planning/execution mechanisms.
     </principles>
 </meta>
 
 <step_1_load>
-    **Role**: System Analyst
     **Action**:
-    1.  **Read Roadmap**: Read `[[__DOCS_DIR__]]/global/roadmap.json`.
-        - **Pre-flight**: Read only the `<ID>` task entry and its direct deps' `id/title/status`; check whether deps are completed, reject Plan if not (unless user forces). No need to load other task data.
-    2.  **Read Vision**: Read `[[__DOCS_DIR__]]/global/vision.md` — extract North Star Metric and Design Philosophy sections only; skip remaining chapters.
-    3.  **Read Tech Stack**: `02_tech_stack.md` (technical red lines + **Section 9 Project Conventions**).
-        - Extract global architecture conventions from Section 9 (Error Handling / Data Flow / Auth & Access) for convention inheritance in step_2.
-    4.  [?UI] **Read Design Tokens**: `[[__DOCS_DIR__]]/global/design_tokens.json`.
-    4.5 [?UI] **Read UI Context**: `[[__DOCS_DIR__]]/global/ui_context.md` (if it exists).
-        - Look up the screen inventory to locate the screen IDs (e.g. S-03) for this task and their state coverage.
-        - Lock the screen scope to fill in `ui.md §1` in step_4; do not invent new screen IDs.
-        - If `ui_context.md` does not exist → skip; write `ui.md` in full ITP format.
-    5.  [?Data] **Read Data Model**: `[[__DOCS_DIR__]]/global/data_snapshot.json`.
-    6.  **Read Dependency Context** (if dependent tasks exist):
-        - Read only the Interface/Type definitions section of the dep's `spec.md` (`## Interface` or `## Types` chapter); skip Scenarios and other content.
-        - Execute only when a `ref: tasks/<dep_id>/spec.md#X` reference appears in the current spec/plan; skip if no reference found.
-        - **Stub Compatibility**: If a dependency's Spec-Status is Stub, extract source files from the stub's "Associated Files", read entry files to extract public interfaces/exported types as upstream interface reference.
-        - Avoid re-defining upstream interfaces; ensure integration points are precisely aligned.
-    7.  **Read Refs** (if any): Read `[[__DOCS_DIR__]]/refs/index.json` (if exists).
-        - Match relevant ref entries by tags and current task description semantics.
-        - Load only matched ref files (`[[__DOCS_DIR__]]/refs/{id}.{ext}`); skip unrelated entries.
-        - If `refs/index.json` does not exist or refs is empty → skip.
-
-    **Output**: Present a **Task Context Brief** to the user:
-    ```
-    ### Task Context: [Task Name] ([ID])
-
-    **Task Type**: [Inferred from ID prefix: Infrastructure / Feature / Quality / Edit]
-    **Goal**: [roadmap task's goal; highlight any [User Presets] if present]
-    **Upstream Dependencies**: [completed dependency tasks and their key interfaces/types, or "None"]
-    **Project Features**: [activated UI/Data/CLI/Lib/API tags]
-    **Technical Constraints**: [key red lines from 02_tech_stack.md]
-    **Design Philosophy**: [North Star Metric and design principles from vision.md]
-    **Project Conventions**: [from 02_tech_stack.md §9 — Error Handling: X | Data Flow: X | Auth: X, or "Not set" if absent]
-    **External knowledge refs**: [matched ref ids, e.g. `wechat-pay`, `company-sdk`; or "None"]
-    ```
-    Retain full context materials internally, proceed to step_2.
+    1.  **Pre-flight**: Read roadmap.json; read only `<ID>` entry and direct deps' `id/title/status`; reject if deps incomplete (unless user forces).
+    2.  **Load**: vision.md (North Star + design philosophy only), 02_tech_stack.md (red lines + §9 project conventions; extract Error Handling/Data Flow/Auth inheritance), (UI projects only) design_tokens.json + ui_context.md (locate screen IDs, lock scope for step_4; do not invent new IDs; skip if absent), (Data projects only) data_snapshot.json.
+    3.  **Dependency Context** (when deps exist): Read only dep task spec.md Interface/Type section; skip if no ref. Stub dep → extract public interfaces from associated files.
+    4.  **Refs** (if any): Read refs/index.json; match by tag semantics; load only matched ref files; skip if absent.
+
+    **Output**: Output **Task Context Brief** to user — include task type (from ID prefix), goal (highlight [User Preset]), upstream deps and key interfaces, project feature tags, tech constraints, design philosophy, project conventions (§9 values, or "not set"), external ref ids (matched). Retain full context internally; enter step_2_complexity.
 </step_1_load>
 
-<step_1_5_complexity>
-    **Role**: Product Consultant
+<step_2_complexity>
     **Action**: Detect task type, assess complexity, decide flow path.
 
-    **⓪ Task Type detection (execute first)**:
-
-    Infer task type from `<ID>` prefix; applies to all subsequent steps:
-
-    | ID Prefix | Task Type | spec § 2 Primary Dimension | spec § 4 Interface Exports |
-    |:---|:---|:---|:---|
-    | `INF-` | Infrastructure | Structural (config contracts) | **Required** (downstream infrastructure) |
-    | `FEAT-` | Feature | Behavioral (behavior scenarios) | Required when has downstream deps |
-    | `POLISH-` | Quality | Quantitative (quality targets) | Usually omit |
-    | `EDIT-` | Edit | Inherit from original task | Inherit |
+    **⓪ Task Type + granularity red lines**:
 
-    > Mixed tasks (e.g. INF task with behavior aspect) may combine dimensions in § 2; use sub-headings to distinguish.
+    | ID Prefix | Task Type | spec § 2 Primary Dimension | § 4 Interface | AC Cap | Phase Cap |
+    |:---|:---|:---|:---|:---|:---|
+    | `INF-` | Infrastructure | Structural (config contracts) | **Required** | ≤ 8 Contracts | ≤ 5 |
+    | `FEAT-` | Feature | Behavioral (scenarios) | Required when has downstream deps | ≤ 6 Scenarios | ≤ 4 |
+    | `POLISH-` | Quality | Quantitative (targets) | Usually omit | ≤ 4 Targets | ≤ 3 |
+    | `EDIT-` | Edit | Inherit from original | Inherit | Inherit | Inherit |
 
-    **① Granularity hard-limit check (by Task Type)**:
-
-    | Task Type | Acceptance Criteria item cap | plan.json Phase cap |
-    |:---|:---|:---|
-    | Feature | ≤ 6 Scenarios | ≤ 4 |
-    | Infrastructure | ≤ 8 Contracts | ≤ 5 |
-    | Quality | ≤ 4 Targets | ≤ 3 |
+    > Mixed tasks may combine dimensions in § 2 with sub-headings. Trigger split when estimate exceeds cap.
 
-    > Estimation method: based on roadmap task goal and dependency context from step_1, quickly enumerate core paths. Trigger if over limit — no precise calculation needed.
-
-    **② Complexity verdict (after granularity passes)**:
+    **① Complexity verdict**:
 
     | Signal | Verdict | Flow |
     |:---|:---|:---|
-    | No deps + no new entities + no architecture decisions + estimated ≤3 tasks | **Simple** | Skip step_2 interview; generate spec + plan directly |
-    | Has deps OR new entities OR architecture decisions needed | **Standard** | Execute step_2 Unified Proposal normally |
-
-    **Simple Mode**:
-    - Skip 5-dimension architecture recommendations and User Confirm Gate
-    - spec condensed to 1-2 Acceptance Criteria items (format by Task Type)
-    - plan condensed to a single Phase
-    - Confirm at signoff (replacing step_2 Gate)
+    | No deps + no new entities + no arch decision + estimated ≤3 tasks | **Simple** | Skip step_2; generate spec + plan directly (condensed single Phase; confirm at signoff) |
+    | Has deps OR new entities OR arch decision needed | **Standard** | Execute step_2 Unified Proposal normally |
 
-    **③ Design signal detection (after Standard verdict)**:
-
-    For Standard tasks, detect whether to generate `design.md` (technical design):
+    **② Design signal detection** (after Standard):
 
     | Signal | Verdict |
     |:---|:---|
-    | Architecture option's AI- contains complexity warning (e.g. "extremely hard to implement correctly", "state management complex", "connection leak") | **Standard + Design** |
-    | Involves custom state machine, non-trivial algorithm, multi-component coordination protocol, retry/recovery strategy | **Standard + Design** |
-    | Standard CRUD / config / simple integration | **Standard** (no design.md) |
-
-    > When Standard + Design: step_2 must output mechanism preview (Part 1.5); step_4 must additionally generate `design.md`.
-</step_1_5_complexity>
+    | AI- contains complexity warning OR involves custom state machine / non-trivial algorithm / multi-component coordination / retry recovery | **Standard + Design** (step_2 output mechanism preview; step_4 add design.md) |
+    | Standard CRUD / config / simple integration | **Standard** |
+</step_2_complexity>
 
-<step_2_interview>
+<step_3_interview>
     **Role**: Architect
 
     ---
 
-    ### Unified Proposal
+    ### Unified Proposal (one-shot)
 
-    **Core principle**: Merge task design and architecture decisions into **one single output**; user confirms or overrides in one round.
+    **Core principle**: Merge task design and architecture decisions into **one output**; user confirms or overrides in one round.
 
     **Action**:
 
     #### Part 1: Task Design
 
-    AI **selects which modules to output** based on the task's nature, from the following material library:
+    AI **decides which modules to output** by task nature; select from:
 
     | Material | When applicable |
     |:---|:---|
     | Flow description (user journey / system flow / command flow) | Multi-step interaction or processing chain |
-    | Core entities & data | New or modified entities involved; existing entities use `→ ref: data_snapshot.json#EntityName` |
-    | Touchpoints (pages / commands / endpoints / methods) | User-facing or external interfaces exist |
-    | Pre-defined decisions | When goal contains `[User Preset]` → highlight and enforce strictly |
+    | Core entities and data | New or modified entities; existing use `→ ref: data_snapshot.json#EntityName` |
+    | Touchpoints (page / command / endpoint / method) | User-facing or external surface |
+    | Pre-defined decisions | When goal has `[User Preset]` → highlight and enforce strictly |
 
     **Reference rules**:
-    - Entities/types already in global → `ref: data_snapshot.json#X`, only describe what this task **adds or modifies**
-    - Design philosophy/principles → `ref: vision.md#PrincipleName`, no need to restate
+    - Entities/types in global → `ref: data_snapshot.json#X`; only describe **additions or changes** for this task
+    - Design philosophy/principles → `ref: vision.md#PrincipleName`; no restatement
     - Upstream interfaces → `ref: tasks/<dep_ID>/spec.md#InterfaceName`
     - Existing design tokens/components → `ref: design_tokens.json#preset` / `ref: dictionary.json#component`
 
-    **Universal requirement**: Use this task's specific entity names and operation names; no generic descriptions
-
+    **Universal requirement**: Use this task's concrete entity names and operation names; no generics
 
     #### Part 2: Architecture Recommendations
 
-    [[SKILL: archi-plan-options|Follow the skill's three-step selection logic (Convention Inheritance -> Tag Routing -> Recommend vs. Expand) to generate architecture recommendations across five dimensions.]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-plan-options/SKILL.md` and follow its three-step logic)]]
-
-    When expanding a Q-table, follow the format in [[SKILL: archi-interview-protocol|the skill's standard output format]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md` and follow its rules)]].
+    [[SKILL: archi-plan-options|Follow the skill's three-step selection (convention inheritance → tag routing → recommend vs expand) to generate arch recommendations from five dimensions.]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-plan-options/SKILL.md` and follow its three-step logic)]]
 
-    #### Part 1.5: Mechanism Preview [?Complex]
+    When expanding Q-table, follow [[SKILL: archi-interview-protocol|skill's standard output format]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md` and follow its rules)]].
 
-    Output only when step_1_5 verdict is **Standard + Design**. List core mechanisms needing technical design and intended pattern:
-
-    ```
-    ### Mechanism Preview (will generate design.md)
-    | Mechanism | Pattern | Brief |
-    |:---|:---|:---|
-    | [name] | [State Machine / Pipeline / Decision Matrix / Protocol] | [one-sentence description] |
-    ```
+    #### Part 1.5: Mechanism Preview (Complex tasks only)
 
-    > User may add/remove mechanisms or change pattern selection here.
+    Output only when step_1_5 verdict is **Standard + Design**. List core mechanisms needing design and intended pattern (Mechanism / Pattern / Brief table). User may add/remove mechanisms or change pattern.
 
     #### Output Format
 
-    ```
-    ## Task Proposal: [Task Name] ([ID])
-
-    ### Task Design
-    [Output per complexity level, see Part 1 above]
-
-    ### Architecture Recommendations
-    | Dimension | Recommended | Source | Rationale |
-    |:---|:---|:---|:---|
-    | Core Structure | [Recommended option] | Task | [1-2 sentences specific to this task] |
-    | Interaction Pattern | [Recommended option] | Task | [Rationale] |
-    | Error Handling | [Convention value] | Project Convention | ref: 02_tech_stack.md §9 |
-    | ... | ... | ... | ... |
-
-    [Only when Standard + Design]:
-    ### Mechanism Preview (will generate design.md)
-    | Mechanism | Pattern | Brief |
-    |:---|:---|:---|
-    | ... | ... | ... |
+    Output **Task Proposal** including: task design (per Part 1), architecture table (dimension/recommendation/source/rationale), (Standard+Design only) mechanism preview table, (dimensions needing user decision only) expanded Q-table (ID/option/description/AI+/AI-, A recommended, Z custom). End with confirmation: OK to accept all; or annotate changes (design fix / dimension override / answer / mechanism change).
 
-    [Only expand option table for dimensions requiring user decision]:
-    **[Q<n>] Question title**
-    > Why user decision is needed (one sentence)
+    **Goal**: Lock `spec`, `ui` (if applicable), `data_snapshot.json` (if applicable).
 
-    | ID | Option | Description | AI+ | AI- |
-    |:---|:---|:---|:---|:---|
-    | A [Recommended] | ... | Concrete behavior (2-3 sentences) | Full sentence | Full sentence |
-    | B | ... | ... | ... | ... |
-    | Z | Custom | (Describe) | - | - |
+    **⌨️ INPUT**: Reply **OK** to accept all (→ enter step_4_global_sync); or free-text changes (→ enter step_3_5_refinement). No fixed format.
+</step_3_interview>
 
-    ---
-    > Reply **OK** to accept all recommendations; or annotate what to change, e.g.:
-    > - Design correction: "Registration doesn't need email verification step"
-    > - Dimension override: "Core Structure=C, Error Handling=B D"
-    > - Question answer: "Q1=B"
-    > - Mechanism change: "Remove Pipeline, reconnection doesn't need that complexity"
-    ```
-
-    **⌨️ INPUT**: Reply **OK** to accept all; or free-text annotations for changes. No fixed format required.
-</step_2_interview>
-
-<step_2_5_refinement>
-    **Role**: Consultant
+<step_3_5_refinement>
     **Trigger**: User reply is not OK — contains corrections, questions, overrides, or logic conflicts.
-    **Action**: Do NOT generate docs. Incorporate user feedback, refresh Unified Proposal and re-output. Wait for confirmation.
+    **Action**: Do not generate docs. Incorporate feedback, refresh Unified Proposal and re-output; await re-confirmation.
     - If task design question → Compare alternatives, re-propose design
-    - If architecture dimension question → Explain differences in this task's context, update recommendation
+    - If architecture dimension question → Explain differences in this task context, update recommendation
     - If dimension override → Replace recommendation directly and adjust related design
-</step_2_5_refinement>
 
-<step_3_global_sync>
-    **Role**: System Admin
-    **Constraint**: MUST update the following global files **BEFORE** generating Task docs.
+    User replies OK → enter step_4_global_sync.
+</step_3_5_refinement>
+
+<step_4_global_sync>
+    **Constraint**: Must update the following global files **before** generating Task docs.
 
-    **Boundary**: Only register **project business domain** content. Architext framework concepts (scripts, scaffold, roadmap, plan, etc.) and framework infrastructure errors are prohibited from registration in global files.
+    **Boundary**: Only register **project business domain** content. Architext framework concepts (scripts, scaffold, roadmap, plan, etc.) and framework infra errors must not be registered.
 
     **Action Checklist**:
     1.  **`map.json`**: Register `[[__DOCS_DIR__]]/tasks/<ID>_<Slug>` in `directoryMapping`; define module responsibility and dependencies in `logicalTopology`.
-    2.  **Data governance sync** (`dictionary.json` / `error_codes.json` / `data_snapshot.json` etc.): Per `03_data_governance.md` rules, incrementally sync new business terms, error codes, Schema from the proposal to corresponding global files.
-    3.  **`map.json` featureRelations**: [[SUBAGENT: archi-feature-relations|mode: register, context: Determine if this Task is aggregator; if yes, register featureRelations entry]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-feature-relations/SKILL.md`, follow mode: register logic)]]
+    2.  **Data governance sync** (`dictionary.json` / `error_codes.json` / `data_snapshot.json` etc.): Per `03_data_governance.md`, incrementally sync new business terms, error codes, Schema to corresponding global files.
+    3.  **`map.json` featureRelations**: [[SUBAGENT: archi-feature-relations|mode: register, context: Determine if this Task is aggregator; if yes register featureRelations entry]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-feature-relations/SKILL.md`, follow mode: register logic)]]
 
-    **Output**: Change diffs of above files (brief).
-</step_3_global_sync>
+    **Output**: Diff summary of above files. Enter step_5_generate.
+</step_4_global_sync>
 
-<step_4_generate>
-    **Role**: Doc Engineer
-    **Input**: Confirmed Unified Proposal (task design + architecture recommendations) + updated global context + Task Type from step_1_5.
+<step_5_generate>
+    **Input**: Confirmed Unified Proposal (task design + arch recommendations) + updated global context + step_1_5 Task Type.
     **Action**: Generate standard docs under `[[__DOCS_DIR__]]/tasks/<ID>_<Slug>/`.
 
-    **1. `spec.md`** (Mandatory):
+    **1. `spec.md`** (required):
     - Template: `templates/spec.template.md`.
 
-    **spec § 2 dimension format by Task Type**:
+    **spec § 2 format by Task Type**:
 
     | Task Type | § 2 Primary Dimension | Format requirement |
     |:---|:---|:---|
-    | Feature | Behavioral | Gherkin (Given/When/Then); each Scenario maps to concrete flow step or exception path from task design |
-    | Infrastructure | Structural | Configuration Contract per config file/service (Path + Key Settings + Constraints + Verify). Key Settings **must state concrete values**; no generic descriptions (e.g. "configure X") |
-    | Quality | Quantitative | Quality Target; each optimization goal has Metric + Baseline + Target + Verify |
+    | Feature | Behavioral | Gherkin (Given/When/Then); each Scenario maps to concrete flow step or exception path in task design |
+    | Infrastructure | Structural | Configuration Contract; one per config file/service (Path + Key Settings + Constraints + Verify). Key Settings **must state concrete values**; no generic descriptions |
+    | Quality | Quantitative | Quality Target; each goal has Metric + Baseline + Target + Verify |
     | Edit | Inherit from original | Same as original task type |
 
-    > Mixed tasks use sub-headings in § 2 to distinguish dimensions (e.g. INF task with Behavioral subsection for hotkey behavior).
+    > Mixed tasks use sub-headings in § 2 to distinguish dimensions.
 
-    **spec § 4 Interface Exports**: INF tasks **required** (downstream infrastructure must declare exports); FEAT tasks required when has downstream deps.
+    **spec § 4 Interface Exports**: INF **required**; FEAT required when has downstream deps.
     **spec § 5 Constraints**: **Required** — extract relevant red lines from vision.md + 02_tech_stack.md.
 
     **General rules**:
-    - Do not invent Acceptance Criteria; each must correspond to concrete content in task design.
+    - Do not invent AC items; each must map to concrete content in task design.
     - If upstream task, must include explicit Interface/Type definitions in § 4.
 
-    **2. `ui.md`** [?UI]:
+    **2. `ui.md`** (when this task involves UI):
     - Template: `templates/ui.template.md`.
     - **With `ui_context.md` (primary path)**:
-      1. **UI Divergence Check** (required before writing `ui.md`): Compare the confirmed task design from step_2 against the screen inventory in `ui_context.md`. [[SKILL: archi-ui-wireframe|Follow the skill protocol to handle UI divergence.]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` and follow its protocol)]]. Criteria and action:
+      1. **UI divergence check** (required before writing `ui.md`): Compare task design with screen index; identify divergence. [[SKILL: archi-ui-wireframe|Follow skill protocol to handle UI divergence]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` and follow its protocol)]].
 
-         | Divergence type | Criteria | Action |
+         | Divergence Type | Criteria | Handling |
          |:---|:---|:---|
-         | No divergence | Screen index matches design | Write `ui.md` directly, reference screen ID |
-         | Minor addition | New state / modal / local area, overall layout unchanged | Call skill (Plan refinement mode) to update `ui_concept.html` + `ui_context.md`; note `MODIFIED: S-XX` in `ui.md` |
-         | Structural divergence | Layout restructure, new standalone screen, flow path change | **Pause** — present divergence summary to user, wait for **OK**, then call skill to update `ui_concept.html` + `ui_context.md`, then write `ui.md` |
-
-      2. After resolving divergence, fill in screen scope and delta components per `ui.template.md`.
-    - **Without `ui_context.md` (fallback path)**: Write full ITP v3.0 component tree, referencing `design_tokens.json` token definitions.
-
-    **3. `design.md`** [?Complex]:
-    - Template: `templates/design.template.md`.
-    - Generate only when step_1_5 verdict is **Standard + Design**.
-    - § 2 Core Mechanisms: Per step_2 confirmed mechanism preview, call [[SKILL: archi-design-patterns|skill's pattern selection guide and standard format to generate mechanism descriptions and run self-checks]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-design-patterns/SKILL.md` and follow its pattern formats and self-check lists)]].
-    - § 3 Parameters: All mechanism numeric values must be concrete; no vague descriptions.
-    - § 4 Invariants: Each must be testable; must map to plan.json test entries.
-    - § 5 Failure Modes: Each failure must have detection + fallback behavior.
-    - § 6 Trace Verification: Trace design path from each spec § 2 AC; fix gaps by returning to § 2 or § 5.
-
-    **4. `plan.json`** (Mandatory):
-    - Template: `templates/plan.template.json`.
-    - Dynamically adjust Phases by project type; ensure each Task's context is self-contained.
-    - Task descriptions explicitly state "Additive Only" + "Respect Unknowns".
-
-    **WBS decomposition three principles (must follow when generating plan.json)**:
-
-    **Principle 1 — Deliverable-oriented**: Each task `title` describes **deliverable** not activity.
-    > ✅ Good: `apps/web/tsconfig.json — strict + path aliases`
-    > ❌ Bad: `Configure TypeScript`
-
-    **Principle 2 — 100% coverage**: After generation, verify coverage:
-    | Check | Rule |
-    |:---|:---|
-    | Each spec § 2 Acceptance Criteria item | Must have ≥1 task covering it |
-    | Each spec § 4 Interface Export | Must have task responsible for creating/exposing it |
-    | Each spec § 5 Constraint | Must be referenced in some task's notes |
-    Add tasks until 100% covered.
+         | No divergence | Screen index matches design | Write `ui.md` directly; reference screen ID |
+         | Minor addition | New state/popup/local area; overall layout unchanged | Call skill to update `ui_concept.html` + `ui_context.md`; note `MODIFIED: S-XX` |
+         | Structural divergence | Layout refactor, new standalone screen, flow path change | **Pause** — output divergence summary to user; wait for **OK**; then call skill to update; then write `ui.md` |
+
+      2. After resolving divergence, fill screen scope and delta components per `ui.template.md`.
+    - **Without `ui_context.md` (fallback)**: Describe full ITP v3.0 component tree; reference `design_tokens.json` token definitions.
+
+    **3. Complex tasks only: `design.md`**:
+    - Template: `templates/design.template.md`. Generate only when **Standard + Design**.
+    - § 2 Core Mechanisms: Per confirmed mechanism preview, call [[SKILL: archi-design-patterns|skill pattern selection guide and standard format to generate mechanism description and run self-check]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-design-patterns/SKILL.md` and follow its pattern format and self-check list)]].
+    - § 3 Parameters: Values must be concrete; no vagueness. § 4 Invariants: Must be testable; map to plan.json test entries. § 5 Failure Modes: Must have detection + fallback. § 6 Trace Verification: Trace from each spec § 2 AC to design path; fix gaps.
+
+    **4. `plan.json`** (required):
+    - Template: `templates/plan.template.json`. Adjust Phases by project type; each Task context self-contained.
+    - Each Phase must include a `rationale` field recording key design decision rationale (user choice / AI recommendation reason).
+
+    **WBS decomposition three principles**:
+
+    **Principle 1 — Deliverable-oriented**: Each task `title` describes **deliverable**, not activity.
+    > Red Flag: `Configure TypeScript` ← should be `apps/web/tsconfig.json — strict + path aliases`
+
+    **Principle 2 — 100% coverage**: Each spec § 2 AC → ≥1 task covers; each § 4 Interface → task creates; each § 5 Constraint → task notes references. Add if missing.
 
     **Principle 3 — Granularity and mutual exclusion**:
     | Signal | Verdict |
     |:---|:---|
-    | Task involves ≥3 unrelated files | Too coarse — split |
-    | Task title cannot map to concrete output file | Too abstract — concretize |
-    | Two tasks modify same file same region | Violates mutual exclusion — merge or redraw boundary |
-    | Task notes single sentence with no verification | Insufficient info — supplement |
-
-    **`decisions` quality standard**:
-    - `rationale` **must include implementation guidance**; not only "why choose" but "how to configure after choosing".
-    > ✅ Good: `pnpm workspace manages apps/ + packages/; Turborepo pipeline: build→lint→type-check three-level cache; root scripts unified entry`
-    > ❌ Bad: `Brief explicitly requires` ← zero implementation guidance
-
-    **`notes` quality standard**:
-    - Format: `[output file path or operation target] · [spec ref] · [key constraints] · Verify: [executable command + expected result]`
-    - Used by `/archi.code` step_4 to locate and run e2e; do not leave empty.
-    > ✅ Good: `Create apps/web/next.config.ts · spec §2.2 · transpilePackages: ['@repo/ui'], output: 'standalone' · no CSS-in-JS · Verify: pnpm --filter web build succeeds (exit 0)`
-    > ❌ Bad: `Configure Next.js · spec §2.2` ← no concrete content, constraints, or verification
-    > ❌ Bad: `Create file · spec §2.1 · Verify: check file exists` ← "check file exists" not executable
-    > **Red Flag**: notes degenerate to title synonym. Each notes must contain information **not present** in title.
-
-    - Run `npx archi render` after generation to produce readable `.md` view.
-</step_4_generate>
-
-<step_5_verify>
-    **Role**: Independent Reviewer
+    | Task touches ≥3 unrelated files | Too coarse — split |
+    | Title cannot map to concrete output file | Too abstract — concretize |
+    | Two tasks modify same file same region | Violates mutual exclusion — merge or redraw |
+    | Notes single sentence with no verification | Insufficient — supplement |
+
+    **`decisions` quality**: `rationale` must include implementation guidance; not just "why choose" but "how to configure".
+    > Red Flag: `Brief explicitly requires` ← zero implementation guidance
+
+    **`notes` quality**: Format `[output file path] · [spec ref] · [key constraints] · Verify: [executable command + expected result]`. Do not leave empty.
+    > Red Flag: notes degenerate to title synonym. Each notes must contain information **not in** title.
+
+    - Run `npx archi render` after generation to produce readable `.md` views. Enter step_6_verify.
+</step_5_generate>
 
-    [[SUBAGENT: archi-silent-audit|mode: plan-docs, context: Review step_4 generated docs (spec.md, ui.md, plan.json, design.md)]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-silent-audit/SKILL.md`, follow mode: plan-docs review dimension table item by item)]]
+<step_6_verify>
+    **Role**: Independent Reviewer
+    [[SUBAGENT: archi-silent-audit|mode: plan-docs, context: Review step_4 generated docs (spec.md, ui.md, plan.json, design.md)]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-silent-audit/SKILL.md`, follow mode: plan-docs review dimension table)]]
 
     [[INCLUDE: shared/verify-result-handling.md]]
-</step_5_verify>
+</step_6_verify>
 
-<step_6_signoff>
-    **Terminal Gate** (Do not skip; must complete before output summary):
+<step_7_signoff>
+    **Terminal Gate** (do not skip): Standard check (task --check + render).
     | Step | Command | Pass Condition |
     |:---|:---|:---|
-    | 1 | `npx archi task --check` | No ERROR-level issues |
-    | 2 | `npx archi render` | `.md` views generated |
-    | 3 | `npx archi task <ID> --status active` | Task marked as in-progress |
-
-    **Action** (After Gate passes):
+    | 1 | `npx archi task <ID> --status active` | Task marked as in-progress |
+
+    **Pre-signoff Checklist** (confirm each item after Gate passes, before Output):
+    □ spec.md § 2 — ACs/scenarios/contracts map to specific design content (no fabrication)
+    □ spec.md § 4 Interface — filled (required for INF tasks / tasks with downstream deps)
+    □ spec.md § 5 Constraints — extracted from vision + tech_stack (not empty)
+    □ plan.json — every AC in spec § 2 → ≥1 task covering it (100% coverage rule)
+    □ plan.json — every task notes includes verification field (not empty, not title paraphrase)
+    □ map.json — tasks/<ID>_<Slug> registered in directoryMapping
+    □ Global files — new terms/error codes/schemas synced (dictionary/error_codes/data_snapshot)
+    □ Step 6 Silent Audit — executed, all CRITICAL issues resolved
+
+    **Action** (after Checklist confirmed):
     1.  Output summary.
 
-    **Output**: Task definition summary with Architecture Confirmation table (each dimension's final choice and rationale) and Next Steps table.
+    **Output**: Task definition summary with architecture confirmation table (each dimension final choice and rationale) and Next Steps:
+
+    | Priority | Action | Notes |
+    |:---|:---|:---|
+    | 1 | `/archi.code <ID>` | Spec and Plan are ready; start implementation (requires user confirmation) |
+    | Optional | Review spec.md / plan.json | Double-check docs before coding |
 </step_6_signoff>
 
 </protocol_plan>

package/dist/templates/en/docs/prompts/recover.md

@@ -1,63 +1,48 @@
 <protocol_recover>
 **Trigger**: `/archi.recover <pack-file>`
-**Goal**: Read the pack file and write all user data (docs, tasks, custom rules) to their corresponding paths in the current project, completing data restore after a framework upgrade.
+**Goal**: Read pack file; write all user data (docs, tasks, custom rules) to corresponding paths in current project; complete data restore after framework upgrade.
 
 <meta>
   <style>Precise, Efficient, Non-interactive</style>
   <language>English</language>
   <principles>
-    1. **User Data Only**: The pack file contains only user data (`global/`, `tasks/`, `scripts/`, custom rules) — no framework files. Write all entries without filtering.
-    2. **Overwrite Always**: If the target file already exists, overwrite it directly without prompting (in an upgrade scenario, existing files are empty templates and safe to replace).
-    3. **Delta Notation**: Label each written file as `ADDED` or `MODIFIED` in the output.
-    4. **No Partial Write**: If any file write fails, stop immediately and report. Already-written files are not rolled back (idempotent — safe to re-run).
+    1. **User Data Only**: Pack file contains only user data (`global/`, `tasks/`, `scripts/`, `refs/`, custom rules); write all; no filtering.
+    2. **Overwrite Always**: When target path exists, overwrite directly (in upgrade scenario old data is empty template; safe to replace).
+    3. **Delta Notation**: Output must label each written file as `ADDED` / `MODIFIED`.
+    4. **No Partial Write**: If any file write fails, stop immediately and report; already-written files are not rolled back (idempotent; safe to re-run).
   </principles>
 </meta>
 
 <step_1_ingest>
   **Role**: Intelligence Analyst
   **Action**:
-  1. Read the file at the `<pack-file>` path.
-  2. Parse the XML; extract the `path` attribute and CDATA content of each `<file>` element under `<files>`.
+  1. Read file at `<pack-file>` path.
+  2. Parse XML; extract `path` attribute and CDATA content of each `<file>` element under `<files>`.
 
-  | Condition | Action |
+  | Condition | Handling |
   |:---|:---|
-  | File not found or unreadable | Stop — ask user to verify path; suggest running `archi pack` to regenerate |
-  | XML malformed | Stop — note file may be corrupted; suggest re-running `archi pack` |
-  | `<files>` is empty | Stop — inform user the pack is empty |
+  | File not found or unreadable | Stop — ask user to check path; suggest running `archi pack` to generate |
+  | XML malformed | Stop — suggest file may be corrupted; re-run `archi pack` |
+  | `<files>` empty | Stop — inform pack is empty |
 
-  **Output**: Internal file list (path + content). Do not output to user.
+  **Output**: Internal file list (path + content); not shown to user.
 </step_1_ingest>
 
 <step_2_apply>
-  **Role**: Senior Engineer
   **Action**:
-  1. For each `<file>` entry:
-     - Use the `path` attribute (relative to project root) as the write target.
-     - If the target file exists → overwrite (mark as `MODIFIED`).
-     - If the target file does not exist → create (mark as `ADDED`).
-     - Write the full CDATA content, preserving original line endings and encoding.
-  2. Note: paths in the pack may contain nested subdirectories (e.g. `tasks/FEAT-001_auth/spec.md`); ensure parent directories exist before writing.
-
-  **Output**:
-  ```
-  ADDED     .architext/global/vision.md
-  ADDED     .architext/global/roadmap.json
-  ADDED     .architext/tasks/FEAT-001_auth/spec.md
-  MODIFIED  .cursor/rules/90_custom_rules.mdc
-  ...
-  ```
+  1. For each `<file>` entry: use `path` (relative to project root) as write target; exists → overwrite (`MODIFIED`), not exists → create (`ADDED`). Write full CDATA content; preserve original line endings and encoding.
+  2. Paths in pack may have nested subdirs; ensure parent dirs exist.
+
+  **Output**: Each file's `ADDED` / `MODIFIED` status list.
 </step_2_apply>
 
 <step_3_signoff>
-  **Action**:
-  1. Output restore summary:
-     - Total files written (ADDED and MODIFIED counted separately)
-  2. Next Steps:
+  **Output**: Restore summary — total files written (ADDED / MODIFIED counted separately) + Next Steps:
 
   | Step | Notes |
   |:---|:---|
-  | Verify framework state | Run `/archi.help` to check project status and recommended next actions |
-  | Clean up pack file | You may delete `<pack-file>` — it is no longer needed |
+  | Verify framework state | Run `/archi.help` to check project state and suggested next actions |
+  | Clean up pack file | May delete `<pack-file>`; no longer needed |
 </step_3_signoff>
 
 </protocol_recover>