architext 0.0.3 → 0.0.5

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

@@ -1,252 +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.
-
-    **Output**: Present a **Task Context Brief** to the user:
-    ```
-    ### Task Context: [Task Name] ([ID])
-
-    **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]
-    ```
-    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
-    **Action**: Assess task complexity to decide whether to run the full step_2 flow:
+<step_2_complexity>
+    **Action**: Detect task type, assess complexity, decide flow path.
 
-    **① Granularity hard-limit check (before complexity verdict)**:
+    **⓪ Task Type + granularity red lines**:
 
-    | Metric | Limit |
-    |:---|:---|
-    | Estimated spec.md Scenario count | ≤ 6 |
-    | Estimated plan.json Phase count | ≤ 4 |
+    | 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 |
 
-    > Estimation method: based on the roadmap task goal and dependency context loaded in step_1, quickly enumerate the core behavior paths. Trigger if over the limit — no need for precise calculation.
+    > Mixed tasks may combine dimensions in § 2 with sub-headings. Trigger split when estimate exceeds cap.
 
-    **② Complexity verdict (only 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 |
+    | 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 |
 
-    **Simple Mode**:
-    - Skip 5-dimension architecture recommendations and User Confirm Gate
-    - spec condensed to 1-2 Gherkin scenarios
-    - plan condensed to a single Phase
-    - Confirm at signoff (replacing step_2 Gate)
-</step_1_5_complexity>
+    **② Design signal detection** (after Standard):
 
-<step_2_interview>
+    | Signal | Verdict |
+    |:---|:---|
+    | 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_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: Follow `archi-plan-options` 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)]]
+    [[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)]]
 
-    When expanding a Q-table, follow the format in [[SKILL: `archi-interview-protocol` Skill's standard output format]][[NO-SKILL: `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md`]].
+    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 Format
-
-    ```
-    ## Task Proposal: [Task Name] ([ID])
+    #### Part 1.5: Mechanism Preview (Complex tasks only)
 
-    ### Task Design
-    [Output per complexity level, see Part 1 above]
+    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.
 
-    ### 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 expand option table for dimensions requiring user decision]:
-    **[Q<n>] Question title**
-    > Why user decision is needed (one sentence)
+    #### Output Format
 
-    | ID | Option | Description | AI+ | AI- |
-    |:---|:---|:---|:---|:---|
-    | A [Recommended] | ... | Concrete behavior (2-3 sentences) | Full sentence | Full sentence |
-    | B | ... | ... | ... | ... |
-    | Z | Custom | (Describe) | - | - |
+    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).
 
-    ---
-    > 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"
-    ```
+    **Goal**: Lock `spec`, `ui` (if applicable), `data_snapshot.json` (if applicable).
 
-    **⌨️ INPUT**: Reply **OK** to accept all; or free-text annotations for changes. No fixed format required.
-</step_2_interview>
+    **⌨️ 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>
 
-<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.  **`dictionary.json`**: Extract **project business** new terms from the proposal to fill `entities`/`verbs`; register new shared tools to `utilities`; register new public components to `components`.
-    3.  [?Data] **`data_snapshot.json`**: Add/modify Schema based on Core Structure recommendation. Prohibited from writing "TBD"; must write field names and types.
-    4.  **`error_codes.json`**: Register new **business** error codes based on Error Handling recommendation. Framework script errors are handled by exit code + stderr; prohibited from registration.
-    5.  **`map.json` featureRelations**: Determine if this task is an "aggregator" — i.e., its core responsibility is to **list, summarize, or dynamically reflect** a class of other tasks (e.g., "list all commands", "aggregate all page entries", "register all routes"). If yes, append one record to `featureRelations`:
-        ```json
-        {
-          "aggregator": "<this task ID or file path>",
-          "sources": "<one-sentence description of what is aggregated, e.g. 'all CLI command tasks'>",
-          "evidence": "<basis, e.g. 'spec.md §X states this task dynamically lists all Y-type tasks'>",
-          "checkNote": "When tasks of this type are added or removed, check whether <aggregator> needs to be updated"
-        }
-        ```
-        If not an aggregator, skip this step.
-
-    **Output**: Change diffs of above files (brief).
-</step_3_global_sync>
-
-<step_4_generate>
-    **Role**: Doc Engineer
-    **Input**: Confirmed Unified Proposal (task design + architecture recommendations) + updated global context.
+    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**: Diff summary of above files. Enter step_5_generate.
+</step_4_global_sync>
+
+<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`.
-    - Convert confirmed task design and architecture recommendations to Gherkin Scenarios.
-    - Each Scenario must map to a concrete flow step or exception path from the task design; do not invent scenarios.
-    - If upstream task, must include explicit Interface/Type definitions.
 
-    **2. `ui.md`** [?UI]:
+    **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 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.
+
+    **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 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`** (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`:
+      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 `archi-ui-wireframe` 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. `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".
-    - **`decisions`**: Fill per dimension; `choice` supports multi-select (e.g. `A B`, space-separated), custom (`Z: …`); `rationale` must explain reasoning for code phase; do not leave empty.
-    - **`notes`**: Fill each task's `notes` with: `[scope] · [spec ref] · [key constraints] · Verify: [concrete operation]`; used by `/archi.code` step_4 to locate context and run e2e; do not leave empty.
-      > Example: `Implement POST /auth/login · spec §3.1 · JWT must not contain password · Verify: curl POST /auth/login returns 200 + token field`
-    - Run `npx archi render` after generation to produce readable `.md` view.
-</step_4_generate>
-
-<step_5_audit>
-    **Role**: Chief Auditor
-    **Checklist**:
-    1.  **Design Fidelity**: Do Scenarios fully cover confirmed task design (flow steps and exception paths)?
-    2.  **Tech Consistency**: Any undeclared tech used?
-    3.  **Data Integrity**: Do Scenario entities match confirmed core entities?
-    4.  **Error Handling**: Is Error Handling recommendation covered?
-    5.  **AX Compliance**: Are Anti-Clobbering and Interface Stability rules followed?
-
-    Silently fix issues; mark critical issues with `⚠️ Risk Warning`.
-</step_5_audit>
-
-<step_6_signoff>
-    **Terminal Gate** (Do not skip; must complete before output summary):
+         | 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 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>
+
+<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_6_verify>
+
+<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 task <ID> --status active` | Task marked as in-progress |
-    | 3 | `npx archi render` | `.md` views generated |
-
-    **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

@@ -0,0 +1,48 @@
+<protocol_recover>
+**Trigger**: `/archi.recover <pack-file>`
+**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**: 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 file at `<pack-file>` path.
+  2. Parse XML; extract `path` attribute and CDATA content of each `<file>` element under `<files>`.
+
+  | Condition | Handling |
+  |:---|:---|
+  | 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); not shown to user.
+</step_1_ingest>
+
+<step_2_apply>
+  **Action**:
+  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>
+  **Output**: Restore summary — total files written (ADDED / MODIFIED counted separately) + Next Steps:
+
+  | Step | Notes |
+  |:---|:---|
+  | 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>