@laitszkin/apollo-toolkit 3.11.7 → 3.12.0

package/solve-issues-found-during-review/SKILL.md

@@ -1,86 +1,58 @@
 ---
 name: solve-issues-found-during-review
 description: >-
-  From a confirmed finding list: fix in severity order (Critical→Low) with minimal patches, validate after each item, forbid speculative polish; document Deferred/CNR with evidence.
-  Done only when code matches governing specs/plans where they apply and security, edge-case, and other inbound review findings are fixed/verified with nothing material open.
-  Use for concrete review excerpts; STOP if vague. Bad: refactor while Critical SSRF open. Good: minimal patch, tests green, evidence cited.
+  用於根據已確認的 review finding 清單逐項修復問題。必須按嚴重度排序、最小化修改、
+  每項修完立即驗證，並在結束前證明 spec 合規與相關安全 / edge-case finding 已真正清乾淨。
 ---
 
-# Solve Issues Found During Review
+# 修復審查發現的問題
 
 ## Dependencies
 
-- Required: none (caller **MUST** supply an existing review report or reconstructable finding list).
-- Conditional: `review-spec-related-changes` when governing `docs/plans/...`, `spec.md`, `tasks.md`, contracts, or checklists bind the changed behavior—**MUST** satisfy **Completion criteria** §1 before declaring done; `review-change-set` for optional re-validation after **code-affecting** fixes; `systematic-debug` when a fix causes unexpected test or runtime failures; **`commit-and-push`** when the user requests **git commit** and/or **push** to persist fixes—**MUST** hand off that leg to **`commit-and-push`** (not bare `git commit` / ungated push).
-- Conditional (completion gate): **`discover-security-issues`** / **`discover-edge-cases`** when the inbound material includes security or edge-case findings, or when completion requires proving those dimensions clean—rerun or equivalent scoped proof **MUST** show no remaining confirmed in-scope issue (see **Completion criteria** §2).
-- Fallback: If `review-change-set` is unavailable after code fixes, **MUST** still verify via targeted tests and `git diff` (or equivalent) and **MUST** document exactly what was run. If the user requested **commit/push** and **`commit-and-push`** is unavailable, **MUST** stop and report.
+- Required: 使用者必須提供既有 review 報告或可重建的 finding 清單
+- Conditional: `review-spec-related-changes`、`review-change-set`、`systematic-debug`、`discover-security-issues`、`discover-edge-cases`、`commit-and-push`
+- Optional: 無
+- Fallback: 若沒有可重建的 finding 清單就必須停止；若 `review-change-set` 不可用，至少要用針對性測試與 diff 證據補足；若使用者要求提交或推送但 `commit-and-push` 不可用，也必須停止
 
-## Non-negotiables
+## Standards
 
-- **MUST** read the **full** report and the affected code **before** editing. **MUST** tie every code change to a **confirmed** finding (explicit severity/title/evidence). **MUST NOT** fix speculative, hypothetical, or “nice-to-have” items unless the report elevated them to confirmed findings.
-- **MUST** process findings in strict severity order: complete **all** Critical before **any** High, then Medium, then Low—**MUST NOT** skip ahead for convenience. Within a tier, follow the reviewer’s stated ordering when present; if severities are missing, treat business-goal / correctness breaks as **High–Critical class** and cosmetic simplification as **Low**.
-- **MUST** validate after each finding’s fix (tests, repro steps, or agreed oracle) **before** starting the next finding at the same or lower priority. **MUST NOT** mark a finding fixed without passing validation.
-- **MUST** keep each fix **minimal** and scoped to the finding: **MUST NOT** bundle unrelated refactors, style sweeps, or scope expansion.
-- This skill **defaults to product code**; **MUST NOT** edit specs, docs, or `AGENTS.md`/`CLAUDE.md` unless the **finding text** explicitly requires it.
-- If a finding cannot be reproduced after investigation, **MUST** record `Could not reproduce` with evidence and **MUST** continue the queue without silently dropping the item.
+- Evidence: 每個修改都要能對應到一條已確認 finding、受影響程式碼與驗證證據
+- Execution: 依嚴重度由高到低處理，每項 finding 修完就驗證，再進入下一項；最後再做全域重驗證
+- Quality: 僅修確認問題，不夾帶順手重構或推測性 hardening；不能重現時必須留下 `Could not reproduce` 證據
+- Output: 交付逐項狀態、驗證證據、spec 合規結果、 ancillary review 清理結果，以及是否真正完成本輪修復
 
-## Completion criteria
+## 技能目標
 
-Declare this workflow **finished** only when **both** clauses below hold. Partial closure of the finding queue is insufficient.
+把 review 報告中的 confirmed findings 轉成一條可追蹤、可驗證、可收斂的修復流程，避免只做表面修改，並在結束前證明相關spec、安全與 edge-case 要求沒有留下實質風險。
 
-1. **Specification conformance**: Every behavior touched by fixes **MUST** match the authoritative specification documents (`spec.md`, `tasks.md`, `checklist.md`, `contract.md`, governing `docs/plans/{change}` prose, plus any checklist items the caller names). **MUST** run **`review-spec-related-changes`** (or an equivalent checklist walk tied to cited requirement IDs plus tests/commands) whenever such docs exist or the user points at a plan path; cite **Met** (or repaired **Partial**) outcomes with file/test evidence in the closing report. If the caller asserts **no** binding spec for the scope, **MUST** state that assumption explicitly and anchor compliance to the issue/report text plus passing validation—**MUST NOT** silently invent spec obligations.
-2. **Ancillary reviews fully cleared**: Confirmed findings from **security audits**, **edge-case / hardening reviews**, and any other labeled review streams in the inbound package **MUST** reach **`Fixed`** (or documented **`Could not reproduce`** with reproducible rationale) **with** reruns or scoped proofs that show no remaining reproducible exploit or edge-case failure **in scope**. **MUST NOT** declare completion while Critical / High-class security issues or correctness-class edge regressions remain open. **`Deferred`** is incompatible with declaring completion unless the caller explicitly rescopes (“out of this pass”) **in writing** in the conversation; otherwise **MUST** keep working or stop with a blocker report listing what still fails completion §2.
+## 驗收條件
 
-`Could not reproduce` on a formerly cited line **counts** toward §2 cleared **only if** investigation evidence excludes stale reports; if reproducibility disagrees between spec §1 and a security/edge claim, **priority is correctness and safety**: resolve the conflict before completion.
+- 每個程式碼改動都能對應到明確的 finding，且沒有混入無關修補
+- 所有 finding 均按嚴重度順序處理，並在每項修復後留下通過的驗證證據
+- 若此範圍受 `docs/plans/...`、`spec.md`、`tasks.md`、`checklist.md` 或 contract 約束，最終已有 spec 合規證據
+- 安全、edge-case 與其他隨附 review finding 已被修復或以可重現證據標記 `Could not reproduce`；若仍有 `Deferred`，只有在使用者明確縮 scope 時才能宣稱本輪完成
 
-## Standards (summary)
+## 工作流程
 
-- **Evidence**: Confirmed finding → code path → minimal patch → validation artifact; closure adds spec traceability and ancillary-review clean signal.
-- **Execution**: Order by severity; optional parallel module groups only when isolation is real; merge without losing fix intent; completion gates §1–§2 after the queue settles.
-- **Quality**: No speculative hardening; conflicts resolved conservatively unless the finding demands an aggressive change.
-- **Output**: Per-finding status, validation proof, **completion-criteria checklist** (spec + ancillary reviews), final re-validation summary, residual/blockers only when completion is explicitly waived by caller rescope.
+1. 先完整閱讀 report 與受影響程式碼；若使用者只說「修 review finding」但沒提供內容，先嘗試從近期輸出或 diff 重建清單，重建失敗就停止
+2. 擷取每條 finding 的嚴重度、標題、證據位置與重現方式，並排除沒有被 reviewer 明確確認的猜測性項目
+3. 按 Critical -> High -> Medium -> Low 排序；只有在工作空間完全隔離且檔案不重疊時，才允許平行處理不同群組，否則一律串行
+4. 逐條處理 finding：先讀程式碼與重現路徑，再用最小修改修復，立刻執行最窄且足夠的驗證；若驗證結果不清楚，交給 `systematic-debug`
+5. 全部 finding 處理完後，對修改範圍做整體重驗證；若是 code-affecting 變更，重新跑 `review-change-set`
+6. 若存在綁定 spec 或計劃檔，使用 `review-spec-related-changes` 證明已重新符合要求；若 inbound package 含安全或 edge-case finding，使用 `discover-security-issues` 或 `discover-edge-cases` 的 rerun / scoped proof 證明該維度已清空
+7. 向使用者輸出逐項狀態、驗證命令、殘留阻塞與本輪是否真的完成；若要求提交或推送，再交給 `commit-and-push`
 
-## Workflow
+## 使用範例
 
-**Chain-of-thought:** After **each** phase, **`Pause →`** guards against speculative fixes and order violations—answer them before edits or merges.
+- 「修這份 review 裡的 HIGH SSRF finding」-> 只修該 finding 對應路徑，跑針對性測試與重現命令，確認通過後才處理下一條
+- 「report 裡還有 edge-case 與 security finding」-> 修完主問題後，還要補 rerun / scoped proof，不能只靠口頭說明就宣稱完成
+- 「reviewer 指的路徑現在不存在」-> 記錄檢查過的 commit 與路徑，若無法重現則標成 `Could not reproduce`，而不是虛構一個修復
 
-### 1) Ingest findings
+## 參考資料索引
 
-Read the supplied report. If the user says “fix review findings” but attached nothing, reconstruct from git/recent outputs; if **no** reconstructable list exists, **MUST** stop and report. Extract each finding: severity, title, evidence (`path:line` or equivalent), reproduction notes.
-   - **Pause →** Can I attach **severity + excerpt + repro** per row—is anything still vague “looks bad”?
-   - **Pause →** Is this finding **explicitly confirmed** by the reviewer, or only a hypothesis I must shelve?
-
-### 2) Order and (optional) parallelize
-
-Sort into Critical → High → Medium → Low. Optionally group by **module** or **business chain** for parallel work **only** if sub-agents with **isolated workspaces** exist and groups do not share half-applied state.
-
-**Parallel path** — One package per independent group; each worker fixes its findings **in severity order locally**, validates, returns branch/diff + status. Merge packages one at a time; on conflict, preserve both fix intents; prefer the **more conservative** behavior unless the finding required aggressiveness; **MUST** flag unresolvable conflicts instead of silently dropping a fix. After merge, run consolidated tests.
-
-**Serial path (default)** — For each finding in global severity order: read code and repro → apply minimal fix → validate (`systematic-debug` if failures are unclear) → record status → next finding.
-   - **Pause →** Am I respecting **tier closure**—no High work started until every Critical has a settled status (`Fixed`, `Deferred`, `Could not reproduce`)?
-   - **Pause →** If parallelizing: could two workers touch **overlapping** symbols or files midway through—if unsure, serialize.
-
-### 3) Full-scope re-validation
-
-After all findings are processed: run relevant tests over touched areas; if code changed and `review-change-set` is available, run it on the post-fix diff; capture `git diff --stat` (or equivalent). **MUST** confirm no confirmed finding remains open without a recorded reason (`Deferred`, `Could not reproduce`, etc.).
-**Before** declaring the engagement complete: apply **Completion criteria**—**(§1)** spec/plan conformance evidence (`review-spec-related-changes` or equivalent cited requirement IDs + commands); **(§2)** reruns or scoped proofs so security / edge-case (and sibling) confirmed issues are **`Fixed`** or evidenced `Could not reproduce`, with nothing Critical/High-class left open unless the caller explicitly rescopes.
-   - **Pause →** Would the **same** reviewer still see **actionable proof** closed for each `Fixed`, or did I rationalize failures away?
-   - **Pause →** Did my consolidated diff sneak in **bonus** unrelated changes—if yes, peel them back?
-   - **Pause →** Would **§1 + §2** pass an external spot-check—is spec coverage documented and ancillary dimensions clean?
-
-### 4) Report
-
-Deliver: (1) Summary by severity. (2) Per finding: `Fixed` / `Could not reproduce` / `Deferred` + location + validation evidence. (3) **Completion criteria block**: §1 spec conformance (tool or checklist + requirement IDs + commands); §2 security/edge-case (and other ancillary) closure with rerun evidence or explicit caller rescope for any intentional exception. (4) Final re-validation (review tool result if any, tests, diff stat). (5) Residual/deferred with reasons—if present, state whether completion was declared or blocked. (6) User-facing next checks before merge (manual QA, integration, etc.).
-   - **Pause →** Could the user rerun **exactly one** cited command per `Fixed` to trust me—is that cited?
-   - **Pause →** Does the report prove **§1 + §2** without hand-waving?
-
-## Notes
-
-- Hypotheses or “might be risky” lines in a report that were **not** confirmed as findings stay **out of scope** for fixes.
-
-## Sample hints
-
-- **Inbound finding slice** — `HIGH | SSRF via webhook URL | src/net/fetch.rs:112 | curl user-controlled URL without allowlist`.
-- **Serial flow** — fix `HIGH #1`, run `cargo test net_fetch` (or the project’s narrowest test), mark `Fixed` **only after green** → then proceed to `HIGH #2`; do **not** batch three HIGH fixes then test once unless a single coherent patch is unavoidable and validation still proves each finding closed.
-- **Status line**: `HIGH SSRF fetch · Fixed · fetch.rs:105-128 · Verified: cargo test net::fetch + manual blocklisted host`.
-- **`Could not reproduce`**: reviewer cited `middleware.ts:77` leak; current tree shows no such path/commit — note commit inspected and bail with evidence, do **not** invent a finding to satisfy the report.
+- `review-spec-related-changes`：驗證修復後仍符合 spec / plan
+- `review-change-set`：修復後的 code-affecting 差異重審
+- `systematic-debug`：修復過程中遇到不明測試或 runtime 問題時使用
+- `discover-security-issues`：清理安全 finding 時的 scoped proof
+- `discover-edge-cases`：清理 edge-case / hardening finding 時的 scoped proof
+- `commit-and-push`：使用者要求提交或推送時的最終交付流程

package/spec-to-project-html/SKILL.md

@@ -1,103 +1,42 @@
 ---
 name: spec-to-project-html
 description: >-
-  Sync the project HTML architecture atlas to active planning specs by driving `apltk architecture --spec <spec_dir>`. Single specs write overlay YAML under `<spec_dir>/architecture_diff/atlas/`; batch member paths resolve to the shared batch-root `architecture_diff/` beside `coordination.md`. The CLI re-renders only the affected proposed-after HTML pages — macro SVG and per-sub-module internal-dataflow diagrams stay zoomable like the base atlas — so `apltk architecture diff` pairs before/after by path under `docs/plans/**/architecture_diff/`. Preserve the two-layer rule and the responsibility split: **subagents only** — each subagent reads ONE affected feature and declares EVERY intra-feature overlay change; the main agent **waits until all subagents finish**, then aggregates outbound summaries and declares **only** cross-feature edges. **Exact CLI spelling:** always `apltk architecture --help`. Ground every declaration in repo evidence; mark `TBD` when code is missing.
+  使用 `apltk architecture --spec <spec_dir>` 將專案 HTML 架構圖同步到活躍規劃文件。單個 spec 寫入 `<spec_dir>/architecture_diff/`，批量 spec 寫入 `coordination.md` 旁的共享 overlay；每個受影響功能由一個可寫子 agent 負責功能內 overlay 更新，主 agent 必須等待全部子 agent 完成後，才能補跨功能邊、渲染並驗證。基礎 atlas 不得被此技能修改。
 ---
 
-# Spec To Project HTML
+# 規劃文件同步到專案 HTML 架構圖
 
-## Dependencies
+## 技能目標
 
-- Required: **`init-project-html`** — its `SKILL.md` is the semantic rulebook; **`apltk architecture --help`** is the verb/flag source of truth. Reuse the same CLI here with `--spec`.
-- Conditional: **`recover-missing-plan`** if a spec pointer is missing.
-- Conditional: **`generate-spec`** / **`implement-specs*`** terminology for requirement IDs.
-- Optional: **`review-spec-related-changes`** when verifying diagram updates against specs.
-- Fallback: spec demands components that are absent from code → declare them but use `TBD` strings or a `gap` token in the role/purpose/dataflow fields; **MUST NOT** mark them as implemented.
+根據 `docs/plans/...` 下的規劃文件，為專案架構圖生成或更新 spec overlay，使評審者能夠透過 `apltk architecture diff` 直接查看 proposed-after 架構變化，同時保持基礎 atlas 不被污染。
 
-## Non-negotiables
+## 驗收條件
 
-- **MUST** read specs in order unless the user directs otherwise: `spec.md` → `design.md` → `contract.md` → coordination notes.
-- **MUST** declare every change through the CLI with `--spec <spec_dir>` (exact verbs/flags: **`apltk architecture --help`**). Single specs write overlay YAML to `<spec_dir>/architecture_diff/atlas/` and re-render only the affected proposed-after HTML pages there. Batch member paths resolve to the shared batch-root `architecture_diff/` beside `coordination.md`, so the whole batch keeps one overlay and one rendered diff. **MUST NOT** hand-edit `architecture_diff/**/*.html` — the renderer owns those files.
-- **MUST** obey the semantic rules from `init-project-html/SKILL.md`:
-  - Sub-module pages stay self-only — express cross-boundary interactions via **edges** (cross-feature or intra-feature), never as sub-module page prose.
-  - Feature pages stay lightweight — cross-sub-module choreography belongs in **edges**, not in `dataflow` prose that pretends to cross features.
-- **MUST** reconcile deltas through the CLI families described in **`--help`**:
-  - Structural changes → `feature` / `submodule` (**add** / **set** / **remove** as appropriate).
-  - Per-sub-module rows → `function`, `variable`, `dataflow`, `error` (**add** / **remove** / **reorder** for dataflow where supported).
-  - Seams → `edge` **add** / **remove** (prefer stable **`--id`** when you may remove the same edge later).
-  - **`submodule remove`** / **`feature remove`** in spec mode populate removal manifests so `diff` can show **removed** pages; renames are usually **remove old slug + add new slug** so the viewer shows remove + add rather than a silent overwrite.
-- **MUST NOT** drop modules that are still present in code just because the spec omits them — keep them, or rewrite role/purpose to flag “out of spec scope”.
-- **MUST** scope reads to the **affected feature modules** from the spec/design diff (plus any feature owning the other end of a cross-feature edge into an affected one). **Subagents own intra-feature overlay writes; the main agent owns cross-feature seams — after all subagents finish:**
-  - Dispatch **one write-capable subagent per affected feature**. Each applies every intra-feature overlay mutation via `apltk architecture ... --spec <spec_dir>` (exact flags: **`--help`**). Each returns **ONLY** a structured summary: sub-module change list, outbound boundary changes (cross-feature edges to add/change/remove), and any `planned` / `gap` markers.
-  - **MUST** wait until **every** dispatched subagent has completed before running any cross-feature **`edge`** mutation, overlay-wide **`meta`** that stitches multiple features, or shared **`actor`** that exists only for cross-feature context.
-  - **Forbidden:** loading every affected feature’s source into the main agent before delegating — that explodes context and produces contradictory overlays.
-- **MUST** run `apltk architecture validate --spec <spec_dir>` after the final mutation. Resolve every reported error before reporting completion.
+- 只透過 `apltk architecture --spec <spec_dir>` 寫入 overlay；單個 spec 產物位於 `<spec_dir>/architecture_diff/`，批量 spec 則寫入 `coordination.md` 同級的共享 overlay；不得手改 `architecture_diff/**/*.html`。
+- 讀取規劃文件時遵循 `spec.md` → `design.md` → `contract.md` → `coordination.md` 的順序；所有重要宣告都能同時回溯到 spec 語句和相關程式碼或設計證據。
+- 對於程式碼尚未實作、但規劃中已經提出的結構，必須顯式使用 `planned`、`gap` 或 `TBD` 標記，而不能偽裝成已落地實作。
+- 按「每個受影響功能一個可寫子 agent」執行 overlay 更新；主 agent 必須等全部子 agent 完成後，才允許補跨功能邊、共享 `meta` 或共享 `actor`。
+- `apltk architecture validate --spec <spec_dir>` 通過，且 `apltk architecture diff` 中的頁面配對正確，沒有懸空邊、孤兒頁面或錯誤的 add/remove 配對。
 
-## Standards (summary)
+## 工作流程
 
-- **Evidence**: cite the spec passage (design subsystem entry) alongside the code path; record the citation in `meta.summary` or in sub-module purposes when relevant.
-- **Execution**: locate the plan set → list affected feature modules → subagent fan-out → **all complete** → cross-feature edges → `render --spec` if batched → `validate --spec` → `diff` check → handover.
-- **Quality**: macro overlay still shows every cross-feature data-row the spec requires; sub-module declarations stay self-only; `apltk architecture diff` opens cleanly with no orphan pages; no dangling edges.
-- **Output**: single specs touch only `<spec_dir>/architecture_diff/atlas/**` (overlay state) and `<spec_dir>/architecture_diff/**/*.html` (renderer output); batch specs write the same artifacts under the batch root beside `coordination.md`. Base `resources/project-architecture/` is **NEVER** mutated.
+1. 先定位本次規劃目錄；使用者明確給出路徑時優先使用，否則結合 `coordination.md` 或 `recover-missing-plan` 找到正確 plan 集，並整理相關需求編號用於追蹤。
+2. 執行 `apltk architecture --help` 取得最新命令形態，然後按 `spec.md`、`design.md`、`contract.md`、`coordination.md` 的順序讀取內容，確定哪些功能、子模組、邊、變數或錯誤語義會發生變化。
+3. 先只列出受影響功能，不要提前把所有原始碼塞進主 agent。除了直接變更的功能，也要納入跨功能邊另一端的功能，確保 overlay 中的跨邊界關係完整。
+4. 為每個受影響功能派發一個可寫子 agent。每個子 agent 只負責自己功能內的 overlay 寫入：子模組、函式、變數、資料流、錯誤，以及功能內邊；若規劃領先於程式碼，則在角色、用途或資料流文案中明確標註 `planned`、`gap` 或 `TBD`。
+5. 子 agent 只返回功能內變更摘要、跨功能邊界變化和待記錄的 `planned/gap` 標記；主 agent 不得重讀已委派功能原始碼，也不得重複寫功能內元件。
+6. 等全部子 agent 完成後，主 agent 統一補跨功能 `edge`、必要的共享 `meta` / `actor`，再執行 `apltk architecture validate --spec <spec_dir>`，並透過 `apltk architecture diff` 檢查 overlay 頁面是否正確映射到 before/after 視圖。
+7. 最終報告至少包含：觸及的 overlay 檔案或 CLI 變更類別、`modified` / `added` / `removed` 數量、所有子 agent 已完成後才開始跨功能連線的確認、未解決的 spec 與程式碼差距，以及後續跟進行動。
 
-## Acceptance criteria (mirrors `init-project-html`)
+## 使用範例
 
-Open the proposed-after viewer (`apltk architecture diff`) and verify both criteria on the overlay pages before reporting completion:
+- 「把這份新 spec 的架構變化渲染成 before/after HTML 對照。」 -> 「讀取 plan 集，按受影響功能分派子 agent，寫入 `architecture_diff/` overlay，並用 `apltk architecture diff` 驗證。」
+- 「批量規劃下多個 spec 共用一份架構 overlay。」 -> 「仍以成員 spec 路徑呼叫 `--spec`，但讓 CLI 自動彙總到 `coordination.md` 同級的共享 overlay 根目錄。」
 
-1. **The macro overlay clearly shows the proposed-after feature × sub-module relationships**, including data flow (**`data-row`**), interaction logic (**`call`** + **`return`**), error handling and rollback (**`failure`**). Any new / changed / removed cross-boundary path the spec implies **MUST** exist as an edge mutation in the overlay — not as sub-module prose.
-2. **Each touched sub-module’s internal overlay diagram clearly shows the function-level interactions inside it**, including function references and variable reads/writes on `dataflow` steps. Declare `function` / `variable` before referencing them so `validate --spec` passes.
+## 參考資料索引
 
-## Workflow
-
-### 1) Resolve spec inputs
-
-User-pointed path wins; otherwise use the batch `coordination.md` or `recover-missing-plan` to find the most recent plan; collect `R…` / `INT-…` IDs for traceability.
-
-### 2) List the affected feature modules (no function bodies yet)
-
-Derive from the spec/design diff which feature modules change: new sub-modules, edge changes, variable changes, error changes, retired sub-modules… **Also** include any feature owning the other end of a cross-feature edge that is being changed (even if that feature’s own spec is untouched). Record only `slug + change-kind`; do not enter function bodies yet.
-
-### 3) Subagents patch features; orchestrator patches cross-feature seams **after** all workers finish
-
-Dispatch one **write-capable subagent per affected feature**. Each subagent owns every intra-feature overlay write and reports outbound boundaries upward. Use **`apltk architecture --help`** for exact `add|set|remove|reorder` spelling.
-
-> **Feature `<slug>` subagent contract (overlay)**
-> - Read this feature’s affected sub-modules and the cited spec passages / requirement IDs.
-> - Apply every intra-feature overlay mutation with `--spec <spec_dir>`: structural (`feature` / `submodule`), rows (`function`, `variable`, `dataflow`, `error`), and intra-feature **`edge`** changes (including failure / rollback between this feature’s own sub-modules). Order `dataflow` so **variable state** reads end-to-end.
-> - Run `apltk architecture validate --spec <spec_dir>` before returning.
-> - **Return ONLY**: (i) sub-module change list, (ii) outbound boundary changes (cross-feature edges add/change/remove with endpoints and suggested kind/label), (iii) any `planned` / `gap` flags for `meta.summary`.
-
-**After every subagent has completed**, the main agent declares **only** cross-feature seams, then renders and validates:
-
-```bash
-# exact flags per edge: see --help
-apltk architecture edge add --spec <spec_dir> --from <featA>/<subA> --to <featB>/<subB> --kind call|return|data-row|failure --label "..." --no-render
-apltk architecture edge remove --spec <spec_dir> --id <stable_id> --no-render
-apltk architecture render --spec <spec_dir>
-apltk architecture validate --spec <spec_dir>
-```
-
-- **Pause →** Do `planned` / `gap` markers read consistently across affected sub-modules?
-- The main agent **MUST NOT** re-declare a subagent’s intra-feature components, and **MUST NOT** open source files for any feature it delegated.
-
-- **Pause →** Does `apltk architecture diff` pair every changed page correctly? If a page shows as add + remove instead of modified, you renamed a slug somewhere — re-check.
-
-### 4) Traceability (suggested)
-
-Use `feature-trace` (or `meta.summary` for spec-only changes) to map spec IDs to implementation status: `met` / `partial` / `planned` / `gap`.
-
-### 5) Report
-
-List overlay files touched (or verb families used), the diff counts (`modified` / `added` / `removed`) from `apltk architecture diff`, confirmation that **all subagents finished before cross-feature wiring**, unresolved spec-vs-code gaps, and any follow-ups.
-
-## Sample hints
-
-- **Batch merge**: each member spec still calls `--spec <member_dir>`, but the CLI resolves writes to the shared batch-root overlay beside `coordination.md`; `diff` shows the batch as one combined architecture delta.
-- **Spec shrinks scope**: prefer `submodule set --role "deprecated: ..."` before `submodule remove` so reviewers see intent.
-- **Design-only change**: still review edges — order shifts surface as edge mutations; `validate --spec` catches dangling references.
-
-## References
-
-- `init-project-html/SKILL.md` — semantic contracts and acceptance criteria.
-- `init-project-html/references/TEMPLATE_SPEC.md` — schema cheat sheet (fields/enums), not a command list.
-- **`apltk architecture --help`** — live CLI reference.
+- `init-project-html/SKILL.md`：基礎語義規則、邊類型與子模組表達約束。
+- `references/TEMPLATE_SPEC.md`：overlay 模式下的欄位、列舉與 diff 配對規則速查表。
+- `recover-missing-plan`：當 plan 路徑缺失或不明確時用於恢復正確 spec 集。
+- `generate-spec`、`implement-specs*`：需求編號和規劃流程的上游來源。
+- `apltk architecture --help`：`--spec` 模式命令與參數的唯一真源。

package/submission-readiness-check/SKILL.md

@@ -1,75 +1,55 @@
 ---
 name: submission-readiness-check
-description: Prepare a repository for safe submission by synchronizing `CHANGELOG.md`, project docs, `AGENTS.md/CLAUDE.md`, and completed planning artifacts before commit, push, PR creation, or release. Use when a workflow is about to submit changes and must avoid missing finalization steps such as stale `Unreleased` notes, unarchived completed spec sets, or unsynchronized agent constraints.
+description: >-
+  用於在 commit、push、PR 或 release 前做最後同步檢查。會確認 `CHANGELOG.md`、
+  專案文件、`AGENTS.md` / `CLAUDE.md` 與已完成的 planning artifacts 是否都已更新到可提交狀態。
 ---
 
-# Submission Readiness Check
+# 提交前就緒檢查
 
 ## Dependencies
 
-- Required: `align-project-documents` and `maintain-project-constraints` before any git submission step.
-- Conditional: `archive-specs` when completed `spec.md` / `tasks.md` / `checklist.md` sets should be converted into categorized project docs and archived, or when existing project docs need normalization into the standard structure.
-- Optional: none.
-- Fallback: If a required dependency is unavailable, or if spec conversion is required but `archive-specs` is unavailable, stop and report the missing dependency instead of submitting partially synchronized changes.
+- Required: `align-project-documents`、`maintain-project-constraints`
+- Conditional: `archive-specs`
+- Optional: 無
+- Fallback: 若必需技能不可用，或明確需要 spec 歸檔但 `archive-specs` 不可用，必須停止並回報，不得給出虛假的 ready verdict
 
 ## Standards
 
-- Evidence: Inspect the actual git diff, staged set, planning artifacts, `CHANGELOG.md`, and current project docs before declaring the repository ready to submit.
-- Execution: Decide whether the target flow is commit/push, PR, or release; normalize completed spec sets when appropriate; synchronize project docs plus `AGENTS.md/CLAUDE.md`; then enforce changelog readiness before any commit, tag, push, PR creation, or release publishing step.
-- Quality: Treat missing or stale changelog entries as blocking issues for submit workflows, preserve unrelated pending `Unreleased` bullets, do not archive active plan sets that still track unfinished scope, and do not hand back a ready verdict until every conditional gate whose scenario is met has actually been completed.
-- Output: Return a ready-to-submit verdict with the synchronized files and any blocking items that must be fixed before the owning submit workflow continues.
+- Evidence: 以實際 git diff、staged set、planning artifacts、`CHANGELOG.md` 與現有專案文件作為就緒判斷依據
+- Execution: 先確認下游提交類型，再處理 spec 歸檔、文件同步與 changelog，最後才給出 ready 或 blocking verdict
+- Quality: 所有命中的條件 gate 都必須真正完成；不能把 stale changelog、未同步文件或仍活躍的 plan set 當成小問題略過
+- Output: 回傳清楚的可提交判定，列出已同步項目與仍阻塞下游提交流程的問題
 
-## Workflow
+## 技能目標
 
-### 1) Inventory the real submission surface
+在任何提交、推送、開 PR 或發版前，先把 repository 的外部說明、內部約束與 planning artifacts 同步到一致狀態，避免把未整理完成的變更交給下一個提交流程。
 
-- Read `git status -sb`, `git diff --stat`, and `git diff --cached --stat`.
-- Check whether the repository has root `CHANGELOG.md`, top-level `AGENTS.md/CLAUDE.md`, and categorized project docs already in use.
-- Inventory planning artifacts across the repository, not only staged files, so completed plan sets are not missed.
-- Classify the intended downstream flow:
-  - `commit-push`
-  - `pull-request`
-  - `release`
+## 驗收條件
 
-### 2) Decide whether planning artifacts should be converted
+- 已盤點真實的提交面，包括 git 狀態、staged diff、現有 docs、planning artifacts 與目標提交流程
+- 當 spec 已完成且應轉成長期文件時，已先完成 `archive-specs`，而不是把它留給後續流程猜測處理
+- `docs/`、`AGENTS.md` / `CLAUDE.md` 與必要的 `README.md` 已根據實際行為與工作流程同步
+- `CHANGELOG.md` 的 `Unreleased` 區塊已準確對應這次將提交、開 PR 或發版的真實範圍
+- 最終輸出的是明確的 ready / blocking verdict，而不是模糊警告
 
-- Treat live `spec.md`, `tasks.md`, and `checklist.md` sets semantically instead of mechanically.
-- Run `$archive-specs` when the relevant plan set reflects the delivered outcome, or when project docs still need normalization into the standard categorized structure.
-- Keep a plan set live when it still documents unfinished implementation, unresolved design work, or same-scope follow-up that is intentionally not shipping yet.
-- If the archive scenario is met, treat `$archive-specs` as blocking before returning a ready-to-submit verdict.
+## 工作流程
 
-### 3) Synchronize project docs and constraints
+1. 先讀取 git 狀態、staged / unstaged diff，並盤點 repo 是否有 `CHANGELOG.md`、`AGENTS.md`、`CLAUDE.md`、標準化 `docs/` 結構，以及任何 `docs/plans/...` 計劃集
+2. 判斷下游流程屬於 `commit-push`、`pull-request` 或 `release`，因為不同流程對 changelog 與發版資料的要求不同
+3. 檢查 planning artifacts 是否應轉檔；只要 plan set 已對應本次交付成果，或專案文件仍未標準化，就必須先跑 `archive-specs`
+4. 在 spec 歸檔判斷完成後，同步專案文件；必要時執行 `align-project-documents` 更新 `docs/`，再用 `maintain-project-constraints` 更新 `AGENTS.md` / `CLAUDE.md`
+5. 檢查 `CHANGELOG.md`：對 commit / PR 流程，要讓 `Unreleased` 精準反映這次待提交內容，同時保留其他未出貨工作；對 release 流程，`Unreleased` 必須非空且已整理成可直接切版的 release notes
+6. 彙整哪些項目已同步、哪些仍阻塞；若還有未完成的 gate，明確回報 blocking item，而不是把責任留給下一個技能
 
-- Run `$align-project-documents` after spec conversion or doc inspection is complete.
-- Run `$maintain-project-constraints` immediately before the owning submission workflow mutates git history.
-- Apply the resulting doc and `AGENTS.md/CLAUDE.md` updates when behavior, operator workflow, or standing project rules changed.
+## 使用範例
 
-### 4) Enforce changelog readiness
+- 「準備提交這批變更」-> 檢查是否有未同步 changelog、文件與已完成但尚未歸檔的 spec
+- 「準備開 PR」-> 確保 `Unreleased` 反映當前 PR 範圍，並把 `AGENTS.md` / `CLAUDE.md` 與 docs 同步好
+- 「準備發版」-> 確保 `Unreleased` 非空且可直接作為 release notes，並先完成任何必要的 spec 歸檔與文件標準化
 
-- Treat root `CHANGELOG.md` as the canonical user-facing submission summary when it exists.
-- For `commit-push` and `pull-request` flows:
-  - Keep `Unreleased` aligned with the actual pending change set.
-  - Add or update only the bullets that correspond to the current work.
-  - Preserve unrelated pending bullets from other unshipped work.
-  - Remove or rewrite stale bullets when the current implementation supersedes them.
-  - If `Unreleased` is missing the current code-affecting or user-visible change, edit `CHANGELOG.md` now instead of returning a warning for another workflow to maybe fix later.
-- For `release` flows:
-  - Require a non-empty `Unreleased` section before the release continues.
-  - Ensure the release workflow will cut notes directly from curated changelog content instead of reconstructing them from `git diff`.
-  - Confirm the `Unreleased` bullets are release-ready before handing control back: they must describe the exact release scope that will be versioned and tagged next.
-- If code-affecting or user-visible changes are about to ship and `CHANGELOG.md` does not reflect them, stop and fix the changelog before continuing.
+## 參考資料索引
 
-### 5) Hand back a submission verdict
-
-- Confirm which files were synchronized:
-  - project docs
-  - `AGENTS.md/CLAUDE.md`
-  - `CHANGELOG.md`
-  - archived plan sets
-- If anything remains unsynchronized, report it as a blocking item rather than letting the submit workflow continue optimistically.
-
-## Notes
-
-- Do not create commits, tags, pushes, PRs, or releases inside this skill.
-- Treat scenario-matched conditional gates such as spec archival, docs synchronization, and changelog updates as blocking readiness work, not optional follow-up.
-- Use this skill as a shared preflight for submit workflows rather than duplicating the same finalization checklist in multiple skills.
+- `align-project-documents`：同步 `docs/features/`、`docs/architecture/`、`docs/principles/`
+- `maintain-project-constraints`：同步 `AGENTS.md` / `CLAUDE.md`
+- `archive-specs`：在符合條件時轉檔並歸檔 planning artifacts

package/systematic-debug/SKILL.md

@@ -1,71 +1,55 @@
 ---
 name: systematic-debug
-description: "Systematic debugging workflow for program issues: understand observed vs expected behavior, inspect codebase paths, reproduce all plausible causes with tests, diagnose the real root cause, and complete a validated fix. Auto-invoke whenever behavior does not match expectations (even if the user did not explicitly request debugging), including bugs, errors, crashes, regressions, flaky behavior, and failing tests."
+description: >-
+  用於系統化排查程式問題。先釐清預期與實際行為，再對所有合理原因做可重現驗證，
+  找出真正根因並以最小修復完成驗證；凡是出現 observed-vs-expected mismatch 都應優先使用。
 ---
 
-# Systematic Debug
+# 系統化除錯
 
-## Standards
+## Dependencies
 
-- Evidence: Gather expected versus observed behavior from code and runtime facts before deciding on a cause, and when the issue involves a runtime pipeline or bounded run, anchor the investigation to one canonical artifact root or run directory instead of mixed terminal snippets from multiple runs; if generated reports or databases drift into an older run directory, capture that mismatch explicitly before treating any artifact as evidence.
-- Execution: Inspect the relevant paths, reproduce every plausible cause with tests or bounded reruns, choose a reproduction mode whose fidelity matches the user's claim, map each observed failure to a concrete pipeline stage, distinguish toolchain/platform faults from application-logic faults, classify failing tests as stale test contract vs test-harness interference vs real product bug, and when tuning a stress, chaos, or edge-case profile preserve a minimal executable path so the rerun still exercises the target lifecycle stage before applying the minimal fix at the true owner.
-- Quality: Keep scope focused on the bug, prefer existing test patterns, explicitly rule out hypotheses that could not be reproduced, treat shared-state or parallel-test interference as a first-class hypothesis when failures disappear in isolated reruns, and when a fault-injection profile wipes out all execution opportunities first classify that as toolchain, harness, or profile invalidation before blaming product logic.
-- Output: Deliver the plausible-cause list, the canonical evidence source, reproduction tests or reruns, the final failure classification for each investigated symptom, validated fix summary, passing-test confirmation, and when runtime profile tuning was involved state whether the final scenario still preserves meaningful executability.
+- Required: 無
+- Conditional: 視情況可搭配 `test-case-strategy`、`analyse-app-logs`、`scheduled-runtime-health-check`
+- Optional: 無
+- Fallback: 無
 
-## Core Principles
+## Standards
 
-- Gather facts from user reports and code behavior before changing implementation.
-- Cover all plausible causes with reproducible tests instead of guessing a single cause.
-- Keep fixes minimal, focused, and validated by passing tests.
-- When logs or runtime artifacts exist, treat one run as canonical and compare every conclusion against that same run's generated artifacts, not against ad hoc console recollection.
-- When comparing runtime runs, first verify the baseline run is complete enough for the requested comparison: same command or scenario, same runtime mode, same bounded duration, and matching structured artifacts. If the baseline is incomplete, report that the only proven change is artifact/run completeness and avoid drawing strategy or performance conclusions from missing data.
-- When a repository has both scenario or harness runs and a production-like runtime, do not treat the lower-fidelity mode as proof about the higher-fidelity mode unless you explicitly state that limitation and the user agrees.
-- When the failing flow crosses multiple layers, identify the last confirmed successful stage before assigning blame.
-- When debugging a stress, chaos, or edge-case profile, keep the profile adversarial but not globally disabling: preserve at least one realistic path that can reach the target stage so the rerun measures product behavior under pressure instead of only proving the harness can self-sabotage.
-- If a profile adjustment restores some execution but the target stage is still unobserved, classify the remaining blocker precisely by stage instead of reporting a blanket recovery.
-- When tests fail, separate stale assertions and fixture drift from real implementation regressions before changing product code.
-- If failures only appear under parallel execution or shared shell-out paths, investigate test isolation, shared locks, temp directories, run-name collisions, and environment leakage before blaming the product.
+- Evidence: 先收集預期與實際行為、程式碼路徑、測試輸出與單一可信 runtime artifact，再判斷原因
+- Execution: 為每個合理假設建立可重現證據，定位最後一個成功階段，再區分工具鏈、測試契約、測試隔離與產品邏輯問題
+- Quality: 修復只針對真實根因；不能重現的假設必須明確排除；不得混用不同執行批次的證據
+- Output: 產出根因候選、重現方式、最終分類、最小修復、驗證結果，以及在 runtime 問題中使用的 canonical evidence
 
-## Trigger Conditions
+## 技能目標
 
-Use this skill by default whenever the request indicates a program problem, including:
+把「它應該做 X，實際卻做了 Y」這類問題轉成可驗證的除錯流程，避免靠猜測改碼，並確保最後交付的是已被重現、已被證明、已被驗證的修復。
 
-- bug, defect, regression, broken behavior
-- error, exception, crash, 4xx/5xx failure
-- failing/flaky tests, intermittent failures, unstable behavior
-- "why is this not working" style troubleshooting requests
-- explicit or implicit observed-vs-expected mismatch ("it should do X but does Y")
+## 驗收條件
 
-Also auto-invoke this skill when mismatch evidence appears during normal execution (logs, test output, runtime output), even if the original request was not phrased as a debugging task.
+- 已清楚記錄預期行為、實際行為、受影響路徑，以及 runtime 問題使用的單一 canonical 證據來源
+- 所有合理根因都已被重現、驗證或明確排除，而不是只修第一個看起來像的原因
+- 已區分問題屬於工具鏈 / 平台、測試契約過期、測試干擾、流程編排，還是真正的產品邏輯缺陷
+- 最終修復是最小且聚焦的，並由失敗後轉成功的測試或 bounded rerun 證明有效
 
-## Required Workflow
+## 工作流程
 
-1. **Understand and inspect**: Parse expected vs observed behavior, explore relevant code paths, record the canonical failing run or artifact root when runtime output is involved, and build a list of plausible root causes.
-2. **Map the failure boundary**: Break the flow into concrete stages such as setup, startup, readiness, steady-state execution, persistence, and shutdown, then identify the last stage that is confirmed to have succeeded.
-3. **Reproduce with tests or bounded reruns**: Write or extend tests that reproduce every plausible cause, and when the bug depends on runtime orchestration rerun the same bounded command or the same runtime mode instead of switching contexts mid-investigation. If the user is asking about real runtime or market behavior, prefer the production-like bounded run over a synthetic scenario replay unless safety or tooling constraints make that impossible. When a failing test passes in isolation, rerun it under the original suite shape to determine whether the real cause is stale expectations, fixture drift, or shared-state interference. When stress or chaos configuration is part of the reproduction, keep the pressure profile strong enough to preserve the intended edge cases while still allowing at least partial traversal of the target lifecycle stage.
-4. **Diagnose and confirm**: Use reproduction evidence to confirm the true root cause, explicitly rule out non-causes, and classify whether each investigated failure belongs to the toolchain/platform layer, test contract drift, test-harness interference, orchestration, or application logic.
-5. **Fix and validate**: Implement focused fixes and iterate until all reproduction tests or bounded reruns pass.
+1. 先整理使用者回報、測試輸出、日誌與程式碼路徑，明確寫出預期與實際差異；若問題涉及 runtime artifact，先指定一個 canonical run 或輸出目錄
+2. 把流程拆成具體階段，例如 setup、startup、readiness、steady-state、persistence、shutdown，找出最後一個已確定成功的階段
+3. 為每個合理根因建立重現方式；能用測試重現就優先用測試，涉及真實執行流程時則用相同模式的 bounded rerun，而不是中途切換到不同 fidelity 的環境
+4. 若失敗只在平行執行、共享 shell-out、共享暫存路徑或舊報告路徑下出現，先調查測試隔離、共享狀態與 artifact routing 問題
+5. 用重現證據確認真正根因，並明確排除非原因；若測試失敗其實來自 stale assertion 或 fixture drift，先修正測試契約，不要反向削弱產品行為
+6. 實作最小修復並反覆驗證，直到所有重現案例、相關測試或 bounded rerun 都通過
+7. 向使用者回報根因清單、最終分類、修復摘要、驗證結果，以及任何仍受限於執行環境或資料品質的部分
 
-## Implementation Guidelines
+## 使用範例
 
-- Read related modules end-to-end before editing.
-- Prefer existing test patterns and fixtures over creating new frameworks.
-- Keep the scope to bug reproduction and resolution; avoid unrelated refactors.
-- If a hypothesized cause cannot be reproduced, document why and deprioritize it explicitly.
-- For long-running or generated-artifact workflows, record the exact command, timestamps, and artifact paths before inspecting outputs so later comparisons stay on the same evidence set.
-- Do not mix baseline data and rerun data casually; compare the same scenario or command across runs and call out when a conclusion comes from a rerun rather than the original failure.
-- When rerun artifacts land in the wrong directory because a wrapper or inherited environment reused a previous report path, fix the evidence layout first and only then compare metrics; otherwise classify the result as an artifact-routing problem rather than a performance delta.
-- For post-run "why did most events not happen" questions, derive the answer from a funnel over structured artifacts first, then corroborate with logs: discovered or eligible candidates, admission blocks, stale or skipped decisions, queue/governor outcomes, execution attempts, confirmations, retries, and persisted event rows.
-- For speed questions, compute per-stage timings from available event timestamps and state which stages are measured versus unavailable; avoid treating wall-clock bounded duration as pipeline latency, and separately report bounded execute time versus provisioning/readiness/cleanup overhead when both are present.
-- When a runtime profile adds extreme faults, distinguish "edge cases are present" from "the harness globally disabled execution"; if every candidate dies before the claimed stage, reduce only the globally disabling parts, keep representative faults, and rerun the same bounded scenario to prove the profile still exercises the target path.
-- When test fixtures or assertions no longer match the implemented contract, update the tests instead of weakening the product behavior to satisfy stale expectations.
-- When tests shell out to shared local infrastructure, add deterministic isolation such as mutexes, unique temp roots, or serialized sections before accepting flakes as inevitable.
+- 「這個 API 應該回 200，現在卻變成 500」-> 先確認預期契約，再重現所有合理根因，最後定位是 handler 邏輯、依賴服務還是測試 fixture 問題
+- 「測試單獨跑會過，但整個 suite 會 flaky」-> 優先排查共享狀態、鎖、暫存目錄與環境污染，而不是先改產品邏輯
+- 「bounded run 幾乎沒有事件發生」-> 先沿著 lifecycle funnel 判斷停在哪個階段，再確認是 profile 過度破壞、編排錯誤，還是實際業務邏輯問題
 
-## Deliverables
+## 參考資料索引
 
-- Plausible root-cause list tied to concrete code paths
-- Canonical failing run or artifact root when runtime evidence exists
-- Reproduction tests or bounded reruns for each plausible cause
-- Failure classification for each symptom: stale contract, harness interference, or real bug
-- Fix summary mapped to failing-then-passing tests
-- Final confirmation that all related tests pass
+- `test-case-strategy`：需要補重現測試或 drift check 時使用
+- `analyse-app-logs`：問題主要來自應用日誌時使用
+- `scheduled-runtime-health-check`：需要有界執行與執行後分析時使用