@laitszkin/apollo-toolkit 4.1.0 → 4.1.2

package/skills/init-project-html/references/architecture.md

@@ -1,40 +1,40 @@
-# apltk architecture — 宣告式架構圖 CLI
+# apltk architecture — Declarative Architecture Diagram CLI
 
-## 用途
-透過 YAML 狀態檔案管理 `resources/project-architecture/` 下的架構圖，支援基礎架構圖與 spec 覆蓋層的差異比對與合併。
+## Purpose
+Manage architecture diagrams under `resources/project-architecture/` via YAML state files. Supports base atlas and spec overlay diff/merge comparison.
 
-## 用法
+## Usage
 ```
 apltk architecture [verb] [options]
 ```
 
-## 全局旗標
-| 旗標 | 效果 |
-|------|------|
-| `--project <root>` | 指定專案根目錄（預設從 cwd 向上搜尋） |
-| `--spec <spec_dir>` | 寫入 spec overlay 而非基礎架構圖 |
-| `--no-render` | 變更後略過自動重新渲染，可批次多條指令 |
-| `--no-open` | `open` 和 `diff` 時不開啟瀏覽器 |
-| `--dry-run` | 預覽變更為 JSON diff，不實際寫入 |
-| `--out <dir>` | `diff` 的輸出目錄 |
-| `--clean` | `merge` 成功後移除 spec overlay 目錄 |
-| `--all` | `merge` 時選取所有 pending spec overlay |
-| `--json` | `status` 時輸出 JSON |
-| `--evidence <level[:source]>` | 為組件標記 observed/inferred/assumed 品質等級 |
-
-## 頂層動詞
-- **`open`** — 開啟基礎架構圖 HTML，若未渲染則先 bootstrap
-- **`diff`** — 收集 `docs/plans/` 下所有 overlay，產生 before/after 檢視器
-- **`render`** — 從當前 YAML 狀態重新產生 HTML
-- **`validate`** — 驗證架構圖結構完整性（schema + referential integrity）
-- **`status`** — 顯示摘要（feature/submodule/edge/actor 數量、時間戳、驗證狀態）
-- **`scan --src <dir>`** — 掃描目錄結構，輸出 JSON 候選 feature 列表
-- **`undo [--steps <n>]`** — 還原最近一次 mutation
-- **`merge --spec <dir> | --all`** — 將 spec overlay 合併回基礎架構圖
-
-## Mutation 系列
-
-所有 mutation 共用 `--project`、`--spec`、`--no-render`、`--dry-run`、`--evidence` 旗標。
+## Global Flags
+| Flag | Effect |
+|------|--------|
+| `--project <root>` | Specify project root (defaults to upward search from cwd) |
+| `--spec <spec_dir>` | Write to spec overlay instead of base atlas |
+| `--no-render` | Skip auto-render after mutations for batch operations |
+| `--no-open` | Skip browser launch for `open` and `diff` |
+| `--dry-run` | Preview changes as JSON diff without writing |
+| `--out <dir>` | Output directory for `diff` |
+| `--clean` | Remove spec overlay directory after successful `merge` |
+| `--all` | Select all pending spec overlays for `merge` |
+| `--json` | JSON output for `status` |
+| `--evidence <level[:source]>` | Mark component quality tier (observed/inferred/assumed); source supports auto-parsed `file:line` (e.g. `observed:src/foo.ts:42`) |
+
+## Top-Level Verbs
+- **`open`** — Open base atlas HTML in browser; bootstrap if not rendered
+- **`diff`** — Collect all overlays under `docs/plans/`, generate before/after viewer
+- **`render`** — Regenerate HTML from current YAML state
+- **`validate`** — Validate atlas structural integrity (schema + referential integrity)
+- **`status`** — Show summary (feature/submodule/edge/actor counts, timestamp, validation status)
+- **`scan --src <dir>`** — Scan directory structure, output JSON candidate feature list
+- **`undo [--steps <n>]`** — Revert the most recent mutation(s)
+- **`merge --spec <dir> | --all`** — Merge spec overlay(s) into base atlas
+
+## Mutation Series
+
+All mutations share `--project`, `--spec`, `--no-render`, `--dry-run`, `--evidence` flags.
 
 ### feature
 ```
@@ -92,7 +92,7 @@ apltk architecture actor add --id <actor-id> [--label "..."]
 apltk architecture actor remove --id <actor-id>
 ```
 
-## 注意事項
-- 執行 mutation 後自動重新渲染（除非 `--no-render`）
-- 每個 mutation 建立 undo snapshot，可行 `undo` 還原
-- 驗證通過後才算架構圖工作完成
+## Notes
+- Auto-render after every mutation (unless `--no-render`)
+- Each mutation creates an undo snapshot — revert with `undo`
+- Atlas work is not complete until validation passes

package/skills/init-project-html/references/definition.md

@@ -1,25 +1,20 @@
-## 功能模塊
+## Feature
 
-功能模塊是直接面向用戶的功能，如：
-- 登陸功能
-- 註冊功能
-- 邀請碼功能
+A feature is a user-facing capability, such as:
+- Login
+- Registration
+- Invite code management
 
-功能模塊由子模塊的合作、交互實現
+Features are realized through collaboration and interaction of their submodules.
 
-功能模塊對應 C4 model 的 **Container** 層級：高階功能邊界，可獨立部署或辨識的系統能力單元。
+A feature maps to the C4 model's **Container** level: a high-level functional boundary, deployable or identifiable as a distinct system capability unit.
 
-## 子模塊
+## Submodule
 
-子模塊是功能模塊的關鍵組成部分。具體定義依照代碼的實作邊界得出。
+A submodule is a key building block of a feature. Its exact definition follows the implementation boundaries in the code.
 
-子模塊對應 C4 model 的 **Component** 層級：功能內部的實作單元（如 controller、service、repository）。
+A submodule maps to the C4 model's **Component** level: an implementation unit inside a feature (e.g., controller, service, repository).
 
-## C4 模型層級對照
+## C4 Level Mapping
 
-| C4 層級 | 對應概念 | 用途 |
-|---------|---------|------|
-| System Context | 整體系統 + 外部 actor | 定義系統邊界與外部依賴 |
-| Container | 功能模塊（feature） | 高階功能邊界 |
-| Component | 子模塊（submodule） | 功能內部的實作單元 |
-| Code | function 行 | 函式層級細節（選擇性） |
+Refer to the C4 mapping table in `SKILL.md` — it is not duplicated here.

package/skills/plan/SKILL.md

@@ -53,7 +53,7 @@ Decompose the architecture design from DESIGN.md into tasks precise to the file
 
 **Decide whether each task needs an independent worker:**
 - Touches ≥2 files → needs independent worker
-- No file overlap between tasks → can run in parallel workers
+- **No file overlap between tasks → workers may run in parallel.** This is permitted ONLY when file lists have ZERO overlap across all workers within the same batch. Any shared file between tasks means sequential execution — this is a hard constraint to prevent overwrite conflicts.
 - File overlap or logical dependency between tasks → must run sequentially
 - Purely procedural operations (lockfile update, merge, commit) → no worker needed; coordinator handles directly
 
@@ -78,13 +78,13 @@ Analyze dependencies between specs:
 
 Output: Spec DAG.
 
-### 5. Detect File Overlap
+### 5. Detect File Overlap (Parallelism Gate)
 
-Perform file overlap detection across all task units:
+File overlap detection is the **gate that determines parallelism**. Perform this across all task units:
 
 1. Collect the file list each task unit is expected to modify
-2. Compare file lists and mark overlaps
-3. File-overlapping task units must not run in parallel and cannot be assigned to different workers
+2. Compare file lists and mark overlaps — zero overlap is the **only** condition for parallel execution
+3. Any file overlap at all → must be sequential. This is a hard constraint — never dispatch parallel workers for tasks sharing a file
 
 ### 6. Write Worker Prompts (One Per Dispatchable Task)
 
@@ -114,8 +114,8 @@ Tasks that do not need a worker (purely procedural operations) do not get a work
 
 Based on dependency analysis and file overlap detection, build the batch schedule → PROMPT.md Section 7 (Batch Schedule).
 
-**Batch partitioning principles:**
-- Within the same batch: tasks have no file overlap and no logical dependency → can dispatch workers in parallel
+**Batch partitioning principles (file overlap is the hard gate):**
+- Within the same batch: tasks must have ZERO file overlap — only then may they dispatch workers in parallel. File-overlapping tasks must be placed in separate sequential batches regardless of dependency
 - Between batches: the previous batch must complete and pass its gate before the next batch begins
 - A final integration batch handles housekeeping tasks (lockfile update, final test suite)
 

package/skills/qa/SKILL.md

@@ -84,17 +84,18 @@ Design principles:
 
 ### 5. Analyze Fix Dependencies → FIX.md Section 4
 
-- **File overlap dependency**: Multiple issues touch the same area of the same file → must be sequential
+- **File overlap dependency**: Multiple issues touch the same file → must be sequential. This is a hard constraint — parallel workers are only permitted when file sets have ZERO overlap, regardless of logical independence
 - **Logical dependency**: Fix B depends on Fix A being completed first
 - **Independent issues**: No file overlap and no logical dependency → can be parallel
 - **Regression test dependency**: Regression tests must run after their corresponding fix is complete (tests verify the fixed code)
 
-### 6. Detect File Overlap
+### 6. Detect File Overlap (Parallelism Gate)
+
+File overlap detection is the **gate that determines parallel vs sequential execution**. Perform this across all fixes and regression tests:
 
-Perform file overlap detection across all fixes and regression tests:
 1. Collect the file list for each fix and regression test
-2. Compare file lists and mark overlaps
-3. Overlapping work must not run in parallel and cannot be assigned to different workers
+2. Compare file lists and mark overlaps — zero overlap is the only condition for parallel execution
+3. Any file overlap at all → must be sequential. This is a hard constraint — never dispatch parallel workers for overlapping files
 
 ### 7. Write Worker Prompts
 
@@ -144,9 +145,9 @@ Each regression test worker prompt must include:
 
 ### 8. Create Batch Schedule → FIX.md Section 7
 
-**Batch partitioning principles:**
-- Fix batches: Ordered by dependencies. P0 issues first.
-- Regression test batches: Dispatched **after all fixes are complete**, because tests verify the fixed code. Regression tests without file overlap can run in parallel.
+**Batch partitioning principles (file overlap is the hard gate):**
+- Fix batches: Ordered by dependencies. P0 issues first. Within each batch, workers require ZERO file overlap to run in parallel — overlapping fixes must be sequentialized across sub-batches
+- Regression test batches: Dispatched **after all fixes are complete**, because tests verify the fixed code. Regression tests without file overlap can run in parallel; those sharing files must be sequential
 - Final batch: Full test suite + lint + confirmation that all issues are resolved.
 
 **Typical schedule:**

package/skills/review/SKILL.md

@@ -32,7 +32,7 @@ Using each requirement's implementation scope and affected files (from DESIGN.md
 
 ### 2. Dispatch Per-requirement Subagents
 
-Create one subagent per requirement (Requirement N). All subagents can review source code in parallel.
+**Mandatory: one agent per requirement.** Every `### Requirement N` must have its own dedicated review agent. Never merge requirements or skip any requirement. All subagents can review source code in parallel.
 
 **If a previous REPORT.md exists**: Condense its verdict and key findings into one history entry. Prepend it to the Review History section, keeping all past rounds. Then perform a fresh review — do not let prior results bias the new assessment.
 
@@ -58,19 +58,51 @@ Each subagent's task:
 | **P2 — Requirement Risk** | Functionality is correct but there are potential risks (architecture deviation, security weakness, performance bottleneck). This finding does **NOT** affect current requirement satisfaction. | → Needs Attention |
 | **P3 — Suggestion** | Functionality is fully correct. Code can be improved but nothing is blocking. This finding does **NOT** affect any requirement's satisfaction. | → Ready to Merge |
 
-If the same code corresponds to multiple requirements, cross-agent findings are handled in the synthesis phase.
+### 3. Identify Cross-requirement Connections
 
-### 3. Synthesize Review Results
+After all per-requirement subagents have completed, analyze the collected findings and requirement scopes to detect interactions:
 
-Collect all subagent findings and synthesize:
+- **Shared modules**: Multiple requirements touch the same code modules or utilities
+- **Shared data structures**: Multiple requirements read/write the same data structures or state
+- **Functional coupling**: One requirement's output feeds into another's input path
+- **Same-file modifications**: Multiple requirements modify the same file (merge conflict risk)
+- **Findings cross-references**: Individual agents flagged code that affects multiple requirements
+
+Group connected requirements into **Requirement Groups**:
+
+- Two requirements are connected if they share any interaction type above
+- Connections are transitive: if A connects to B and B connects to C, all three form one group
+- An isolated requirement (no connections to any other) is its own group of size 1
+
+Output: Requirement Groups list, each with:
+- Grouped requirement IDs
+- Interaction type (shared module, shared data, functional coupling, file overlap)
+- Interaction summary for group-level review
+
+### 4. Dispatch Group Subagents
+
+Create one review agent per Requirement Group. Each group agent reviews the **interactions between requirements** within its group:
+
+1. Read the individual review findings for all requirements in the group
+2. Focus on interaction-level concerns:
+   - **Interface mismatch**: One requirement's output consumed by another — does the contract align?
+   - **Side effect risk**: Changes for one requirement break assumptions of another
+   - **Merge conflict potential**: Same-file modifications require careful ordering
+   - **Architecture consistency**: Combined changes maintain DESIGN.md integrity
+3. Classify interaction findings using the same severity scale (P0-P3)
+4. Report findings scoped to the group interaction
+
+### 5. Synthesize Review Results
+
+Collect findings from both per-requirement and group subagents:
 
 1. **Dedup overlapping findings**: Merge identical issues found by multiple agents into a single finding. Preserve dimension-specific notes from each agent.
-2. **Resort by severity**: Reorder all findings by P0 → P3 across the entire list (not per-agent order).
+2. **Resort by severity**: Reorder all findings by P0 → P3 across the entire list.
 3. **Collapse empty severity levels**: If a severity level has zero findings, do NOT generate its table header or column labels.
-4. **Cross-requirement interaction check**: Identify code introduced for one requirement that modifies shared modules or data structures used by another requirement. Flag these as potential interaction risks (P2).
-5. **Conditional dimension summary**: If total findings exceed 5, include a one-line summary of finding counts per dimension. Otherwise omit — the findings table itself is sufficient.
+4. **Include group-level findings**: Cross-requirement interaction findings sit alongside individual findings.
+5. **Conditional dimension summary**: If total findings exceed 5, include a one-line summary of finding counts per dimension. Otherwise omit.
 
-### 4. Generate REPORT.md
+### 6. Generate REPORT.md
 
 Use `assets/templates/REPORT.md` and populate accordingly.
 
@@ -88,8 +120,6 @@ Include the following sections:
 | No P0/P1, has P2 findings | Needs Attention |
 | Only P3 or no findings | Ready to Merge |
 
-The verdict is derived directly from the severity of findings. P0 and P1 are defined as "requirement not satisfied" — if they exist, the review must fail. If only P3 exists, requirements are satisfied and no P3 finding can block a merge.
-
 **The report must NOT contain** fix suggestions, root cause analysis, or verification methods. These are handled by the `qa` skill.
 
 ## References

package/skills/update-project-html/README.md

@@ -1,42 +1,31 @@
 # update-project-html
 
-`update-project-html` refreshes the project HTML architecture atlas (`resources/project-architecture/`) so it reflects the latest code changes.
-
-## What this skill does
-
-1. Reads the current atlas (`atlas.index.yaml` + per-feature YAML) — only affected features (context economy).
-2. Measures architecture drift: compares atlas entries against actual codebase structure.
-3. Resolves the diff scope (`git diff --stat` + `git diff --cached --stat` by default, or `git diff --stat <base>..HEAD` when the user names a ref).
-4. Filters out non-architecture changes (formatting, config-only, test-only, comments).
-5. Maps filtered diff hunks to existing or new features.
-6. Dispatches one write-capable subagent per affected feature to deep-read only its own changed files and apply every intra-feature mutation through `apltk architecture` (no `--spec`).
-7. Waits until every subagent finishes, then declares cross-feature edges, runs `apltk architecture render`, and validates.
-8. Re-measures drift to confirm it is within acceptable range.
+Refreshes the project HTML architecture atlas (`resources/project-architecture/`) to reflect the latest code changes.
 
 ## When to use
 
-Use this skill when the task asks you to:
-
-- update or refresh the existing project architecture diagram after code changes,
-- bring `resources/project-architecture/` back in sync with the current branch or a specific commit range,
-- reflect a recent PR or batch of commits in the canonical atlas before merging or releasing.
+- The existing atlas is out of sync with the current branch or working tree
+- Code has changed (new routes, modules, service logic) and the atlas needs updating before a release
+- You need to bring `resources/project-architecture/` back in sync after a PR or batch of commits
 
-If no atlas exists yet, use `init-project-html` to bootstrap one. For planned but unshipped work scoped to a `docs/plans/...` spec, use `spec-to-project-html` to write under `<spec_dir>/architecture_diff/` instead of the base atlas.
+If no atlas exists yet, use [`init-project-html`](../init-project-html/SKILL.md) to bootstrap one first.
 
 ## Core principles
 
-- The CLI owns atlas state and renderer output; agents never hand-edit `resources/project-architecture/**/*.html`.
-- Every mutation traces to a specific file + diff hunk; absent code never produces atlas entries.
-- Subagent fan-out is the only safe read pattern: one feature per subagent, no shared source loading.
-- Cross-feature wiring happens **after** every subagent finishes — never from partial summaries.
-- Measure drift before and after: confirm the atlas stays within an acceptable drift threshold.
-- Filter diff noise: formatting, config-only, test-only, and comment-only changes never drive atlas mutations.
+- The CLI owns atlas state and rendered output; never hand-edit `resources/project-architecture/**/*.html`
+- Every mutation traces to a specific file + diff hunk; absent code never produces atlas entries
+- Measure drift **before and after**: confirm the atlas stays within acceptable thresholds
+- Filter diff noise: formatting, config-only, test-only, and comment-only changes never drive atlas mutations
+
+## Workflow
+
+See [`SKILL.md`](./SKILL.md) for the full 6-step workflow.
 
 ## References
 
-- [`SKILL.md`](./SKILL.md) — full workflow and execution rules.
-- [`../init-project-html/SKILL.md`](../init-project-html/SKILL.md) — semantic rulebook.
-- [`../spec-to-project-html/SKILL.md`](../spec-to-project-html/SKILL.md) — spec overlay flow.
+- [`SKILL.md`](./SKILL.md) — Full workflow and execution rules
+- [`../init-project-html/SKILL.md`](../init-project-html/SKILL.md) — C4 semantic rulebook
+- [`../init-project-html/references/TEMPLATE_SPEC.md`](../init-project-html/references/TEMPLATE_SPEC.md) — Atlas field reference and schema
 
 ## License
 

package/skills/update-project-html/SKILL.md

@@ -1,70 +1,83 @@
 ---
 name: update-project-html
-description: 當項目架構圖與實際程式碼脫節時，增量刷新架構圖資源。包括基礎 atlas 與渲染 HTML。更新前先測量 drift 程度決定更新範圍。
+description: Incrementally refresh the architecture atlas when the project diagram drifts from actual code. Measures drift before updating to determine scope, then updates the base atlas and re-renders HTML.
 ---
 
-## 目標
+## Goal
 
-根據目前分支、工作區或指定提交範圍內的程式碼變更，增量刷新基礎 atlas 與渲染 HTML。
-使架構圖持續和實際程式碼保持一致。
+Incrementally refresh the base atlas and rendered HTML based on code changes in the current branch, working tree, or a specified commit range.
+Keep the architecture diagram continuously aligned with the actual codebase.
 
-## 驗收條件
+## Acceptance Criteria
 
-- 所有子模塊之間的 edge 的定義被更新到貼合最新代碼實踐
-- 所有子模塊內部的 edge 的定義被更新到貼合最新代碼實踐
-- 架構圖完整展示整個系統之中子模塊之間的關係以及功能模塊之間的關係
-- 已測量架構圖與程式碼的 drift 程度，確認更新範圍合理
-- diff 中不影響架構的變更（formatting、config-only、test-only）已被過濾
+- Architecture drift has been measured before and after the update; the update scope is justified
+- All cross-module and intra-module edges reflect the latest code
+- Every declared component is backed by source code evidence (`evidence.sourceFile:sourceLine`); unresolved ones are tagged `inferred`
+- Non-architectural changes (formatting, config-only, test-only) have been filtered from the diff
 
-## 工作流程
+## Workflow
 
-### 1. 查看現有架構圖
+### 1. Review the current atlas
 
-閱讀現有架構圖。
-整理功能模塊之間、子模塊之間的關係等重要資訊。
+Read the existing architecture diagram.
+Capture the relationship between features and submodules.
 
-> 只讀取 `atlas.index.yaml` + 受影響 feature 的 YAML 檔案。不讀取無關的 feature 或未變更的模組，以維持 context economy。
+> Read only `atlas.index.yaml` + the YAML files of affected features. Do not read unrelated features or unchanged modules to preserve context economy.
 
-### 2. 測量架構 drift
+### 2. Measure architecture drift
 
-在決定更新範圍前，先比對架構圖與當前程式碼的偏離程度：
+Before deciding the update scope, compare the atlas against the current code:
 
-- 比較 `atlas.index.yaml` 與當前目錄結構：是否有新增 / 移除的目錄或模組？
-- 比較各 feature YAML 中的檔案路徑與實際程式碼：是否有檔案已不存在或搬移？
-- 量化 drift：新增 + 移除 + 修改的 entries 數量 / 總 entries 數量
+- Compare `atlas.index.yaml` with the current directory structure: are there added / removed directories or modules?
+- Compare file paths in each feature YAML against the actual codebase: are any files missing or moved?
+- Quantify drift: count of added + removed + modified entries / total entries
 
-根據 drift 程度決定更新策略：
-- **低 drift（< 20%）**：只更新受 diff 影響的 feature
-- **高 drift（≥ 20%）**：建議標記為重大偏離，通知用戶後考慮全面重新初始化（使用 `init-project-html`）
+Determine the update strategy based on drift severity:
+- **Low drift (< 20%)**: Update only the features affected by the diff
+- **High drift (≥ 20%)**: Flag as significant divergence, notify the user and recommend a full re-initialization via `init-project-html`
 
-### 3. 過濾 diff 噪聲
+### 3. Filter diff noise
 
-分析 diff 範圍，過濾不影響架構的變更類型：
-- **保留**：新增或修改的 API route、service 邏輯、資料庫操作、模組邊界變更
-- **過濾**：formatting 調整、config 值變更（非結構變更）、純測試檔案、型別定義調整（非邊界影響）、註解或文檔變更
+Analyze the diff scope and filter non-architectural changes:
 
-將過濾後的 diff hunk 對應到受影響的 feature。
+- **Keep**: New or modified API routes, service logic, database operations, module boundary changes
+- **Filter**: Formatting adjustments, config value changes (non-structural), test-only files, type definition adjustments (no boundary impact), comment or documentation changes
 
-### 4. 對照代碼庫及當前架構圖
+Map the filtered diff hunks to the affected features.
 
-並行調度 subagents 完成代碼與架構圖的對照任務，驗證架構圖是否存在錯誤或遺漏。
+### 4. Cross-reference code with the current atlas
 
-### 5. 通過 `apltk` cli 工具更新當前架構圖
+Dispatch subagents in parallel to cross-reference the code against the architecture diagram and verify whether the atlas has errors or omissions.
 
-使用 `apltk` cli 工具，按照以下流程完成架構圖的更新：
+### 5. Update the atlas via `apltk` CLI
 
-在操作前先閱讀 `references/architecture.md` 了解所有參數細節。
-1. 定義功能模塊及其下屬子模塊。
-2. 定義子模塊之間的關係、呼叫、錯誤處理、資料流、回滾等架構關係
-3. 定義子模塊內部的函數、變數、資料流及錯誤處理。
+Use `apltk architecture` commands to update the architecture diagram:
 
-當從 diff 推斷 component 時，使用 `--evidence inferred` 標記品質等級。例如：
+Consult `references/architecture.md` for CLI flag details (parameter reference, mutation series).
+
+1. Define features and their submodules.
+2. Define inter-submodule relationships: calls, error handling, data flow, rollback, and other architectural connections.
+3. Define intra-submodule functions, variables, data flows, and error handling.
+
+When inferring components from a diff hunk, use `--evidence inferred` with a `file:line` source. For example:
 ```
-apltk architecture function add --feature <slug> --submodule <slug> --name <fn> --evidence "inferred:<source-path>"
+apltk architecture function add --feature <slug> --submodule <slug> --name <fn> \
+  --evidence inferred:src/auth/controller.ts:42
 ```
 
-更新完成後再次測量 drift，確認已降低至可接受範圍。
+After completing the update, re-measure drift to confirm it has been reduced to an acceptable range.
+
+### 6. Self-review
+
+Confirm the following before finishing:
+
+- [ ] Drift is now within acceptable range (< 20%)
+- [ ] Filtered diff noise (formatting, config-only, test-only) did not drive any atlas mutations
+- [ ] Every new or modified component carries evidence (`observed` for source-confirmed, `inferred` otherwise)
+- [ ] All edges affected by changed code have been reviewed and updated
+- [ ] Atlas passes `apltk architecture validate`
 
-## 參考資料
+## References
 
-- `references/architecture.md` — apltk architecture 工具的完整參數說明。在步驟 5 更新架構圖前閱讀，了解 mutation 指令與 --evidence 旗標的行為。
+- `references/architecture.md` — Full parameter reference for the apltk architecture tool (consult when CLI flag details are needed).
+- `references/definition.md` — Detailed definitions of feature and submodule.

package/skills/update-project-html/references/architecture.md

@@ -1,40 +1,40 @@
-# apltk architecture — 宣告式架構圖 CLI
+# apltk architecture — Declarative Architecture Diagram CLI
 
-## 用途
-透過 YAML 狀態檔案管理 `resources/project-architecture/` 下的架構圖，支援基礎架構圖與 spec 覆蓋層的差異比對與合併。
+## Purpose
+Manage architecture diagrams under `resources/project-architecture/` via YAML state files. Supports base atlas and spec overlay diff/merge comparison.
 
-## 用法
+## Usage
 ```
 apltk architecture [verb] [options]
 ```
 
-## 全局旗標
-| 旗標 | 效果 |
-|------|------|
-| `--project <root>` | 指定專案根目錄（預設從 cwd 向上搜尋） |
-| `--spec <spec_dir>` | 寫入 spec overlay 而非基礎架構圖 |
-| `--no-render` | 變更後略過自動重新渲染，可批次多條指令 |
-| `--no-open` | `open` 和 `diff` 時不開啟瀏覽器 |
-| `--dry-run` | 預覽變更為 JSON diff，不實際寫入 |
-| `--out <dir>` | `diff` 的輸出目錄 |
-| `--clean` | `merge` 成功後移除 spec overlay 目錄 |
-| `--all` | `merge` 時選取所有 pending spec overlay |
-| `--json` | `status` 時輸出 JSON |
-| `--evidence <level[:source]>` | 為組件標記 observed/inferred/assumed 品質等級 |
-
-## 頂層動詞
-- **`open`** — 開啟基礎架構圖 HTML，若未渲染則先 bootstrap
-- **`diff`** — 收集 `docs/plans/` 下所有 overlay，產生 before/after 檢視器
-- **`render`** — 從當前 YAML 狀態重新產生 HTML
-- **`validate`** — 驗證架構圖結構完整性（schema + referential integrity）
-- **`status`** — 顯示摘要（feature/submodule/edge/actor 數量、時間戳、驗證狀態）
-- **`scan --src <dir>`** — 掃描目錄結構，輸出 JSON 候選 feature 列表
-- **`undo [--steps <n>]`** — 還原最近一次 mutation
-- **`merge --spec <dir> | --all`** — 將 spec overlay 合併回基礎架構圖
-
-## Mutation 系列
-
-所有 mutation 共用 `--project`、`--spec`、`--no-render`、`--dry-run`、`--evidence` 旗標。
+## Global Flags
+| Flag | Effect |
+|------|--------|
+| `--project <root>` | Specify project root (defaults to upward search from cwd) |
+| `--spec <spec_dir>` | Write to spec overlay instead of base atlas |
+| `--no-render` | Skip auto-render after mutations for batch operations |
+| `--no-open` | Skip browser launch for `open` and `diff` |
+| `--dry-run` | Preview changes as JSON diff without writing |
+| `--out <dir>` | Output directory for `diff` |
+| `--clean` | Remove spec overlay directory after successful `merge` |
+| `--all` | Select all pending spec overlays for `merge` |
+| `--json` | JSON output for `status` |
+| `--evidence <level[:source]>` | Mark component quality tier (observed/inferred/assumed); source supports auto-parsed `file:line` (e.g. `observed:src/foo.ts:42`) |
+
+## Top-Level Verbs
+- **`open`** — Open base atlas HTML in browser; bootstrap if not rendered
+- **`diff`** — Collect all overlays under `docs/plans/`, generate before/after viewer
+- **`render`** — Regenerate HTML from current YAML state
+- **`validate`** — Validate atlas structural integrity (schema + referential integrity)
+- **`status`** — Show summary (feature/submodule/edge/actor counts, timestamp, validation status)
+- **`scan --src <dir>`** — Scan directory structure, output JSON candidate feature list
+- **`undo [--steps <n>]`** — Revert the most recent mutation(s)
+- **`merge --spec <dir> | --all`** — Merge spec overlay(s) into base atlas
+
+## Mutation Series
+
+All mutations share `--project`, `--spec`, `--no-render`, `--dry-run`, `--evidence` flags.
 
 ### feature
 ```
@@ -92,7 +92,7 @@ apltk architecture actor add --id <actor-id> [--label "..."]
 apltk architecture actor remove --id <actor-id>
 ```
 
-## 注意事項
-- 執行 mutation 後自動重新渲染（除非 `--no-render`）
-- 每個 mutation 建立 undo snapshot，可行 `undo` 還原
-- 驗證通過後才算架構圖工作完成
+## Notes
+- Auto-render after every mutation (unless `--no-render`)
+- Each mutation creates an undo snapshot — revert with `undo`
+- Atlas work is not complete until validation passes

package/skills/update-project-html/references/definition.md

@@ -1,25 +1,20 @@
-## 功能模塊
+## Feature
 
-功能模塊是直接面向用戶的功能，如：
-- 登陸功能
-- 註冊功能
-- 邀請碼功能
+A feature is a user-facing capability, such as:
+- Login
+- Registration
+- Invite code management
 
-功能模塊由子模塊的合作、交互實現
+Features are realized through collaboration and interaction of their submodules.
 
-功能模塊對應 C4 model 的 **Container** 層級：高階功能邊界，可獨立部署或辨識的系統能力單元。
+A feature maps to the C4 model's **Container** level: a high-level functional boundary, deployable or identifiable as a distinct system capability unit.
 
-## 子模塊
+## Submodule
 
-子模塊是功能模塊的關鍵組成部分。具體定義依照代碼的實作邊界得出。
+A submodule is a key building block of a feature. Its exact definition follows the implementation boundaries in the code.
 
-子模塊對應 C4 model 的 **Component** 層級：功能內部的實作單元（如 controller、service、repository）。
+A submodule maps to the C4 model's **Component** level: an implementation unit inside a feature (e.g., controller, service, repository).
 
-## C4 模型層級對照
+## C4 Level Mapping
 
-| C4 層級 | 對應概念 | 用途 |
-|---------|---------|------|
-| System Context | 整體系統 + 外部 actor | 定義系統邊界與外部依賴 |
-| Container | 功能模塊（feature） | 高階功能邊界 |
-| Component | 子模塊（submodule） | 功能內部的實作單元 |
-| Code | function 行 | 函式層級細節（選擇性） |
+Refer to the C4 mapping table in `SKILL.md` — it is not duplicated here.