architext 0.0.2

package/dist/templates/zh-Hant/docs/global/design_tokens.json

@@ -0,0 +1,135 @@
+{
+  "_comment": "由 /archi.start 基於 Brief「風格與調性」和「視覺參考」生成。所有值須從 Brief 推導，禁直接複用任何範本預設值。",
+  "scope": "[?UI]",
+  "status": "drafting",
+
+  "aestheticDirection": {
+    "preset": "",
+    "_presetOptions": "saas-dark | saas-light | dashboard | marketing | mobile-app | editorial | brutalist | custom",
+    "customDescription": ""
+  },
+
+  "primitivePalette": {
+    "neutral": {
+      "50": "",
+      "100": "",
+      "200": "",
+      "300": "",
+      "400": "",
+      "500": "",
+      "600": "",
+      "700": "",
+      "800": "",
+      "900": "",
+      "950": ""
+    },
+    "brand": {}
+  },
+
+  "semanticTokens": {
+    "colors": [
+      { "token": "Background", "light": "", "dark": "", "usage": "頁面背景" },
+      {
+        "token": "Surface",
+        "light": "",
+        "dark": "",
+        "usage": "卡片, 彈窗, 側邊欄"
+      },
+      {
+        "token": "Primary",
+        "light": "Brand-?00",
+        "dark": "Brand-?00",
+        "usage": "主按鈕, 激活狀態"
+      },
+      { "token": "Text-Main", "light": "", "dark": "", "usage": "正文, 標題" },
+      {
+        "token": "Text-Muted",
+        "light": "",
+        "dark": "",
+        "usage": "次要資訊, 註解"
+      },
+      { "token": "Border", "light": "", "dark": "", "usage": "邊框, 分隔線" },
+      {
+        "token": "Destructive",
+        "light": "",
+        "dark": "",
+        "usage": "刪除, 錯誤提示"
+      }
+    ],
+    "typography": [
+      {
+        "role": "H1",
+        "fontFamily": "",
+        "size": "",
+        "weight": "",
+        "lineHeight": ""
+      },
+      {
+        "role": "H2",
+        "fontFamily": "",
+        "size": "",
+        "weight": "",
+        "lineHeight": ""
+      },
+      {
+        "role": "Body",
+        "fontFamily": "",
+        "size": "",
+        "weight": "",
+        "lineHeight": ""
+      },
+      {
+        "role": "Small",
+        "fontFamily": "",
+        "size": "",
+        "weight": "",
+        "lineHeight": ""
+      }
+    ]
+  },
+
+  "layout": {
+    "radius": {
+      "sm": "",
+      "md": "",
+      "lg": "",
+      "full": "9999px"
+    },
+    "shadow": {
+      "sm": "",
+      "md": ""
+    },
+    "spacing": {
+      "unit": "4px",
+      "scale": [1, 2, 3, 4, 6, 8, 12, 16]
+    }
+  },
+
+  "mode": {
+    "default": "",
+    "support": []
+  },
+
+  "motion": {
+    "preference": "",
+    "easing": {
+      "standard": "",
+      "decelerate": "",
+      "accelerate": ""
+    },
+    "duration": {
+      "instant": "",
+      "fast": "",
+      "normal": "",
+      "slow": "",
+      "pageTransition": ""
+    },
+    "patterns": {}
+  },
+
+  "illustration": {
+    "style": "",
+    "iconLibrary": "",
+    "emptyStateAsset": ""
+  }
+}

package/dist/templates/zh-Hant/docs/global/dictionary.json

@@ -0,0 +1,35 @@
+{
+  "entities": [
+    {
+      "term": "[業務術語]",
+      "definition": "[一句話定義]",
+      "codeName": "[PascalCase / camelCase]",
+      "forbiddenSynonyms": [],
+      "reference": "[來源: spec / vision / task ID]"
+    }
+  ],
+  "verbs": [
+    {
+      "verb": "[業務動作]",
+      "definition": "[一句話定義]",
+      "codeName": "[camelCase]",
+      "context": "[使用場景]",
+      "reference": "[來源]"
+    }
+  ],
+  "utilities": [
+    {
+      "name": "[工具名, 如 logger]",
+      "path": "[檔案路徑, 如 src/utils/logger.ts]",
+      "purpose": "[用途說明]",
+      "replaces": "[替代的原始 API, 如 console.log]"
+    }
+  ],
+  "components [?UI]": [
+    {
+      "name": "[元件名]",
+      "path": "[檔案路徑]",
+      "purpose": "[用途說明]"
+    }
+  ]
+}

package/dist/templates/zh-Hant/docs/global/error_codes.json

@@ -0,0 +1,19 @@
+{
+  "protocolMapping [?API]": [
+    {
+      "statusCode": "[400 | EXIT_1 | ...]",
+      "code": "[ERR_VALIDATION]",
+      "meaning": "[含義]",
+      "action": "[呼叫方行為: Toast / Exit / Retry / ...]"
+    }
+  ],
+  "businessErrors": [
+    {
+      "module": "[MODULE]",
+      "code": "ERR_[MODULE]_[REASON]",
+      "statusCode": "",
+      "message": "[使用者/開發者可見的錯誤描述]",
+      "recovery": "[恢復建議]"
+    }
+  ]
+}

package/dist/templates/zh-Hant/docs/global/map.json

@@ -0,0 +1,94 @@
+{
+  "governance": {
+    "coreRules": [
+      {
+        "file": "00_system.md",
+        "role": "System Role",
+        "when": "每次對話開始時 (身份設定, 核心原則)"
+      },
+      {
+        "file": "01_workflow.md",
+        "role": "SOP",
+        "when": "決定當前任務流程 (Task vs Fix) 與驗收標準"
+      },
+      {
+        "file": "02_tech_stack.md",
+        "role": "Tech Stack",
+        "when": "技術選型、程式碼規範、工程治理標準"
+      },
+      {
+        "file": "03_data_governance.md",
+        "role": "Data Governance",
+        "when": "讀寫全域 JSON 資料檔案時"
+      },
+      {
+        "file": "04_cli_tools.md",
+        "role": "CLI Reference",
+        "when": "執行 Terminal Gate 命令時 (npx archi task/plan/render 語法速查)"
+      },
+      {
+        "file": "99_context_glue.md",
+        "role": "Context Bridge",
+        "when": "觸碰程式碼時，自動關聯上下文檔案"
+      }
+    ],
+    "globalReference": [
+      {
+        "file": "roadmap.json",
+        "role": "Roadmap",
+        "content": "進度追蹤、里程碑、技術債管理"
+      },
+      {
+        "file": "vision.md",
+        "role": "Vision",
+        "content": "願景、北極星指標、設計哲學"
+      },
+      {
+        "file": "map.json",
+        "role": "Map (本檔案)",
+        "content": "目錄結構、檔案索引、邏輯拓撲"
+      },
+      {
+        "file": "dictionary.json",
+        "role": "Dictionary",
+        "content": "業務術語、公共元件註冊表"
+      },
+      {
+        "file": "design_tokens.json",
+        "role": "Visuals [?UI]",
+        "content": "顏色、字型、間距變數"
+      },
+      {
+        "file": "data_snapshot.json",
+        "role": "Data [?Data]",
+        "content": "資料庫 Schema 鏡像"
+      },
+      {
+        "file": "error_codes.json",
+        "role": "Errors",
+        "content": "錯誤碼與協議契約"
+      }
+    ]
+  },
+  "featureDocs": [
+    {
+      "file": "spec.md",
+      "category": "Specification",
+      "purpose": "業務邏輯、演算法、驗收標準 (Logic)"
+    },
+    {
+      "file": "ui.md",
+      "category": "UI/UX",
+      "purpose": "任務級 UI 範圍聲明 — 引用 ui_context.md 中的畫面 ID，指定本任務涵蓋的畫面/元件範圍"
+    },
+    {
+      "file": "plan.json",
+      "category": "Plan",
+      "purpose": "詳細步驟拆解與測試案例 (Execution)"
+    }
+  ],
+  "directoryMapping": [],
+  "logicalTopology": [],
+  "criticalUserJourneys": [],
+  "featureRelations": []
+}

package/dist/templates/zh-Hant/docs/global/roadmap.json

@@ -0,0 +1,39 @@
+{
+  "version": 1,
+  "projectStatus": "planning",
+  "lastUpdated": "YYYY-MM-DD",
+  "phases": [
+    {
+      "id": "phase-1",
+      "name": "Infrastructure",
+      "tasks": [
+        {
+          "id": "INF-01",
+          "title": "Project Scaffolding",
+          "status": "pending",
+          "description": "",
+          "goal": "",
+          "deps": [],
+          "tag": "Infra",
+          "slug": "Project_Scaffolding"
+        }
+      ]
+    },
+    {
+      "id": "phase-2",
+      "name": "Core Features",
+      "tasks": [
+        {
+          "id": "FEAT-01",
+          "title": "Example Task",
+          "status": "blocked",
+          "description": "",
+          "goal": "",
+          "deps": ["INF-01"],
+          "tag": "Core",
+          "slug": "Example_Task"
+        }
+      ]
+    }
+  ]
+}

package/dist/templates/zh-Hant/docs/global/vision.md

@@ -0,0 +1,82 @@
+---
+description: Project Constitution: Vision, Personas, Principles & Boundaries.
+---
+
+# Product Vision: [項目名稱]
+
+> **Version:** 1.0.0
+> **Status:** Active
+> **Role:** The "Constitution" of the project. All Tasks and Specs must align with this.
+
+## 1. Core Vision (核心願景)
+
+**Elevator Pitch:**
+[產品名稱] 是一個 [目標市場/類別] 平台，旨在幫助 [目標用戶] 解決 [核心痛點]，通過 [核心解決方案/獨特點] 實現 [最終價值]。
+
+**North Star Metric (北極星指標):**
+
+* [指標名稱]: [描述 - 例如：用戶每日專注時長]
+
+---
+
+## 2. Target Audience (目標用戶與畫像)
+
+### Primary Persona (核心用戶)
+
+* **Role:** [例如：備考的學生]
+* **Key Traits:** [關鍵詞]
+* **Pain Points:**
+  * [痛點 1]
+  * [痛點 2]
+* **Goals:**
+  * [希望達成的結果]
+
+---
+
+## 3. Product Principles (產品原則)
+
+* **[原則 1]:** [例如：極簡優先 - 任何增加點擊的操作都需要額外理由]
+* **[原則 2]:** [例如：鼓勵而非懲罰 - 完不成任務時給鼓勵，而不是紅色的警告]
+
+---
+
+## 4. Design & Experience (設計與體驗語言) [?UI]
+
+> **Note:** 本節僅適用於有 UI 的專案。具體色值和圓角定義請嚴格參閱 `[[__DOCS_DIR__]]/global/design_tokens.json`。
+
+### Visual Style (視覺風格)
+
+* **Keywords:** [例如：溫暖、專注、無干擾]
+* **Density:** [例如：大留白，沉浸式]
+* **Animation:** [例如：輕微的微交互，不要花哨的轉場]
+
+### Tone of Voice (文案語調)
+
+* **Personality:** [例如：像一個陪讀的夥伴，而不是嚴厲的老師]
+* **Do's:** [例如：用"我們一起"代替"你應該"]
+* **Don'ts:** [例如：不要使用機械的錯誤碼報錯]
+
+---
+
+## 5. Boundaries (邊界與反目標)
+
+### In Scope (核心範圍)
+
+* [核心功能 A]
+* [核心功能 B]
+
+### Out of Scope (明確不做)
+
+* **[反目標 1]:** [例如：不做社交排行榜]
+* **[反目標 2]:** [例如：不提供深色模式切換（默認即深色）]
+
+---
+
+## 🤖 AI Maintenance Guide
+
+**Trigger**: 僅在項目初始化 (`/archi.start`) 或重大戰略轉型 (`/archi.revise`) 時修改。
+
+**Action**:
+1.  **Alignment**: 確保 Section 3 (Principles) 與 `02_tech_stack.md` 中的技術選型不衝突。
+2.  **Completeness**: 必須填滿所有 `[ ]` 佔位符，嚴禁保留 "Example" 字樣。
+3.  **Consistency**: 所有的 Task Spec (`.spec.md`) 都必須引用此文件的 Vision 以確保不跑題。

package/dist/templates/zh-Hant/docs/prompts/audit.md

@@ -0,0 +1,150 @@
+<protocol_audit>
+  **Trigger**: `/archi.audit [id]`
+  **Goal**: 獨立深度程式碼審查。帶 `<id>` 審查該任務的程式碼實現；無 `<id>` 執行專案級體檢。不修改程式碼，僅輸出審查報告與修復工單。
+
+<meta>
+    <style>Investigative, Thorough, Evidence-Based</style>
+    <language>繁體中文</language>
+    <principles>
+      1.  **Read-Only**: 禁改任何程式碼檔案。審查 ≠ 修復。
+      2.  **Evidence-Based**: 每個發現須附檔案路徑、行號、程式碼片段。
+      3.  **Actionable Output**: 每個問題須附推薦修復命令（`/archi.fix`, `/archi.edit` 等）。
+      4.  **Vision Anchored**: 始終以 `vision.md` 為方向基準，偵測偏離。
+      5.  **Report Persistence**: 審查結果須寫入檔案 — 任務級 → `tasks/<id>_*/audit.md`（覆蓋），專案級 → `audits/YYYY-MM-DD.md`（按日期存檔，同日覆蓋）。
+    </principles>
+</meta>
+
+<step_1_resolve>
+    **Role**: 系統分析師
+    **Mode Gate**:
+
+    | 輸入 | 模式 | 後續步驟 |
+    |:---|:---|:---|
+    | `/archi.audit <id>` | 任務級深度審查 | step_2_task → step_3_report |
+    | `/archi.audit` | 專案級體檢 | step_2_project → step_3_report |
+
+    **任務級 — Resolve ID**:
+    1.  從 `[[__DOCS_DIR__]]/global/roadmap.json` 解析 `<id>` → Task Name、Slug、狀態。
+    2.  **Status Gate** — 僅 `active` 或 `done` 可審查:
+
+        | 狀態 | 處理 |
+        |:---|:---|
+        | `active` / `done` | 通過 |
+        | `pending` | 拒絕 — 無程式碼可審查，先執行 `/archi.plan` + `/archi.code` |
+        | `blocked` | 拒絕 — 前置依賴未完成 |
+
+    3.  **Load Context**:
+        - `[[__DOCS_DIR__]]/global/vision.md` — 專案方向基準
+        - `[[__DOCS_DIR__]]/tasks/<id>_<Slug>/spec.md` — 功能邏輯
+        - `[[__DOCS_DIR__]]/tasks/<id>_<Slug>/plan.json` — 任務清單
+        - `[[__DOCS_DIR__]]/tasks/<id>_<Slug>/ui.md` — 任務 UI 範圍聲明(如存在)
+        - [?UI] `[[__DOCS_DIR__]]/global/ui_context.md` — AI 畫面索引（定位對應畫面 ID）
+        - [?UI] `[[__DOCS_DIR__]]/global/ui_concept.html` — 唯讀視覺參考（#10 合規對比的視覺標準源）
+        - `[[__DOCS_DIR__]]/tasks/<id>_<Slug>/audit.md` — 上次審計報告(如存在，用於對比)
+        - `02_tech_stack.md` — 技術紅線
+        - [?UI] `[[__DOCS_DIR__]]/global/design_tokens.json`
+        - [?Data] `[[__DOCS_DIR__]]/global/data_snapshot.json`
+    4.  讀取該任務對應的所有程式碼檔案。
+
+    **專案級 — Load Overview**:
+    1.  讀取 `[[__DOCS_DIR__]]/global/vision.md`、`roadmap.json`、`map.json`。
+    2.  讀取 `02_tech_stack.md`。
+    3.  掃描 `[[__DOCS_DIR__]]/tasks/` 目錄結構。
+    4.  讀取專案程式碼入口檔案與關鍵模組。
+
+    **Output**: 審查範圍與上下文清單。
+</step_1_resolve>
+
+<step_2_task>
+    **Role**: 首席審計官
+    **Scope**: 任務級深度程式碼審查（僅 `/archi.audit <id>` 時執行）。
+
+    逐維度審查，每個發現須附 `檔案:行號` + 程式碼片段 + 嚴重級別：
+
+    | # | 維度 | 審查要點 |
+    |:---|:---|:---|
+    | 1 | **Vision 對齊** | 實現方向與 `vision.md` 有無衝突或偏離 |
+    | 2 | **Spec 完整性** | 程式碼是否覆蓋 `spec.md` 全部場景與邊界 |
+    | 3 | **Plan 真實性** | 標記 `done` 的任務是否在程式碼中落地（防虛標） |
+    | 4 | **邏輯正確性** | 業務邏輯錯誤、矛盾、遺漏分支、狀態機缺陷 |
+    | 5 | **Bug 獵殺** | 空值/undefined、競態、資源洩漏、死迴圈、off-by-one |
+    | 6 | **錯誤處理** | 吞錯、靜默失敗、錯誤傳播鏈完整性、使用者可見回饋 |
+    | 7 | **Tech Stack 合規** | 對照 `02_tech_stack.md`：違禁模式、過時 API、硬編碼 |
+    | 8 | **安全性** | 敏感資訊洩露、輸入未校驗、注入風險、權限檢查 |
+    | 9 | **效能** | 不必要全量匯入/大迴圈/無用計算/記憶體洩漏/N+1 查詢 |
+    | 10 | [?UI] **Design 合規** | 樣式是否用 Token 定義的視覺模式；無硬編碼魔法值；實現與 `ui_concept.html` 對應畫面視覺一致 |
+    | 11 | [?Data] **資料一致性** | 欄位名/型別與 `data_snapshot.json` 是否一致 |
+    | 12 | [?I18n] **I18n 合規** | 無硬編碼字串；須用 Key/字典引用 |
+    | 13 | **Orphan .gitkeep** | 目錄已有其他檔案時仍存在 `.gitkeep` — 須刪除 |
+    | 14 | **Spec-Code 漂移** | 程式碼中的介面/型別/行為是否與 `spec.md` 一致；手動變更是否已同步到文件 |
+    | 15 | [?UI] **UI 引用完整性** | `ui.md` 中的 `ref: ui_concept.html#S-XX` 指針是否仍然有效；被引用的畫面/元件是否因 edit/revise 後已改名或刪除 |
+
+    **Output**: 按維度分組的發現列表，每項含級別、位置、描述。
+</step_2_task>
+
+<step_2_project>
+    **Role**: 首席審計官
+    **Scope**: 專案級健康體檢（僅 `/archi.audit` 無參數時執行）。
+
+    | # | 檢查項 | 說明 |
+    |:---|:---|:---|
+    | 1 | **Vision 漂移** | `roadmap.json` 任務方向與 `vision.md` 是否一致 |
+    | 2 | **架構一致性** | `map.json` vs 實際目錄結構，有無漂移或未註冊模組 |
+    | 3 | **Roadmap 健康度** | 一致性 + 進度統計 + 長期 blocked 任務 + 依賴環偵測 |
+    | 4 | **檔案完整度** | 各 Task 是否有 spec.md + plan.json；有無孤兒目錄 |
+    | 5 | **Tech Stack 全域合規** | 抽查關鍵入口與模組，偵測全域性違規 |
+    | 6 | **跨 Task 一致性** | 重複邏輯、命名衝突、介面不一致 |
+    | 7 | **Orphan .gitkeep** | 目錄已有其他檔案時仍存在 `.gitkeep` — 須刪除 |
+
+    掃描後標註優先級，推薦需深度審查的 Task：
+    - `done` 但 plan 未全部完成的
+    - 程式碼量大但無測試的
+    - 長期 `active` 未推進的
+
+    **Output**: 專案健康概覽 + 深度審查推薦列表。
+</step_2_project>
+
+<step_3_report>
+    **Role**: 報告撰寫員
+    **Action**:
+
+    **Issue Classification**:
+
+    | 級別 | 含義 | 範例 |
+    |:---|:---|:---|
+    | `CRITICAL` | 須修復，阻塞發布 | 邏輯錯誤、安全漏洞、資料損壞風險 |
+    | `WARNING` | 應修復，有風險 | 缺少錯誤處理、效能隱患、Spec 覆蓋不全 |
+    | `INFO` | 建議最佳化 | 命名不規範、缺少註解、可簡化的程式碼 |
+
+    **Issue Format** (每項須包含):
+    ```
+    [LEVEL] 檔案路徑:行號 — 維度名
+      描述：具體問題
+      -> 推薦修復：/archi.fix <ID> <描述> 或 /archi.edit <ID> <描述>
+    ```
+
+    **Action Routing** (根據問題型別推薦命令):
+
+    | 問題型別 | 推薦命令 |
+    |:---|:---|
+    | Bug（邏輯錯誤、邊界遺漏） | `/archi.fix <ID> <描述>` |
+    | Spec 缺漏（功能未完整實現） | `/archi.edit <ID> <補充描述>` |
+    | 架構級問題（全域違規） | `/archi.revise <描述>` |
+    | 功能未完成（plan 虛標 done） | `/archi.code <ID>` |
+    | 小問題（命名、註解、簡化） | 下次 `/archi.code` 時一併處理 |
+
+    **Report Structure**:
+    1.  審查概要（模式、範圍、日期）
+    2.  發現列表（按級別排序：CRITICAL → WARNING → INFO）
+    3.  統計摘要（各級別數量）
+    4.  修復工單彙總（可直接執行的命令列表）
+    5.  Next Steps 表格
+
+    **Write Report File**:
+    - 任務級 → `[[__DOCS_DIR__]]/tasks/<id>_<Slug>/audit.md`（覆蓋式）
+    - 專案級 → `[[__DOCS_DIR__]]/audits/YYYY-MM-DD.md`（按日期存檔，同日覆蓋）
+
+    **Output**: 完整審查報告（同時輸出到對話和寫入檔案）。
+</step_3_report>
+
+</protocol_audit>