@laitszkin/apollo-toolkit 3.11.8 → 3.12.0

package/review-spec-related-changes/SKILL.md

@@ -1,82 +1,47 @@
 ---
 name: review-spec-related-changes
 description: >-
-  Read-only spec compliance vs governing docs/plans: score every business requirement Met/Partial/Not-met from code/tests/commands—checked `tasks.md` boxes never count; ambiguity between two plan roots halts execution; on code-bearing diffs run **`review-change-set`**, **`discover-edge-cases`**, **`discover-security-issues`** on the same scope afterward — **prefer one read-only subagent per secondary skill in parallel** so the main agent aggregates without re-reading. Independent requirement clusters may also be scored by parallel read-only subagents.
-  Use for “does this PR satisfy coordination.md + spec.md R2?” or a user-pinned `{change}` folder.
-  Do not mutate repos, bury missing goals, skip the tertiary bundle on code-bearing diffs, or rest on intent without evidence; FORBIDDEN to lead with refactor comments while R1 is failing. GOOD: pair every Not-met cite with a `spec.md` ref + concrete path:test gap.
+  面向spec合規性的只讀審查技能。先唯一確定本次變更受哪一套 `docs/plans/...` 規劃文件約束，再按業務目標逐條判定 `Met`、`Partially met`、`Not met` 或 `Deferred/N/A`；`tasks.md` 的勾選不算證據。若範圍涉及代碼實作，完成業務結論後還必須對同一範圍追加 `review-change-set`、`discover-edge-cases` 與 `discover-security-issues`，並保持固定報告順序。
 ---
 
-# Review Spec Related Changes
-
-## Dependencies
-
-- Required: `review-change-set`, `discover-edge-cases`, and `discover-security-issues` whenever the scope includes **code-affecting** implementation to assess.
-- Conditional: none.
-- Optional: none.
-- Fallback: If any required dependency is unavailable for a **code-affecting** review, **MUST** stop and report the gap. **MUST NOT** emit a “full pass” verdict without those three passes when code is in scope.
-
-## Non-negotiables
-
-- **MUST NOT** edit implementation code, tests, or planning docs during this skill (read-only review).
-- **MUST NOT** archive specs, commit, push, tag, or release from this skill.
-- **MUST** resolve which spec set governs the change **before** concluding; if multiple candidates fit equally and cannot be disambiguated from repo evidence, **MUST** stop and report ambiguity—**MUST NOT** guess.
-- **MUST** classify each business goal / acceptance item as `Met`, `Partially met`, `Not met`, or `Deferred/N/A` **only** using verifiable evidence (code, tests, commands, traces)—checked boxes in `tasks.md` are **not** proof by themselves.
-- **MUST** treat **unmet or partially met required business goals** as **highest severity**. **MUST NOT** let edge-case, security, or style findings **outrank** those gaps in the reported order or implied priority.
-- **MUST** finish the business-goal verdict **before** invoking secondary skills; **MUST** still run `review-change-set`, `discover-edge-cases`, and `discover-security-issues` on the **same** implementation scope when code is involved (after step 1 verdict is written).
-- **SHOULD** parallelize the secondary reviews when code is involved by dispatching **one read-only subagent per secondary skill** (one for `review-change-set`, one for `discover-edge-cases`, one for `discover-security-issues`). Each subagent receives the same diff scope, follows that skill’s own SKILL.md, and returns ONLY its structured findings; the main agent aggregates them in the fixed report order without re-running the underlying analysis. Single-file or trivial diffs may be reviewed inline without subagents.
-- For business-goal scoring itself, **MAY** parallelize by dispatching one read-only subagent per **independent requirement cluster** (requirements that share no owned paths and no shared spec section), each returning Met/Partial/Not-met with cited evidence. The main agent owns final ordering, severity, and any cross-requirement reconciliation. Tightly coupled requirements stay on the main agent.
-- **MUST NOT** rest conclusions on author intent, branch names, or chat memory unless **repository evidence** agrees.
-- **MUST NOT** let subagents mutate repositories, archive specs, or commit — every dispatched subagent runs in **read-only** mode.
-- Prefer **fewer confirmed findings** over broad speculation; unproven items belong under **Residual uncertainty**, not as faux defects.
-
-## Standards (summary)
-
-- **Evidence**: Full read of governing docs + minimal code/diff context + spec-named verification commands when safe to run.
-- **Execution**: Scope resolution → business compliance (optionally fanned out by independent requirement cluster) → parallel secondary reviews via per-skill read-only subagents → aggregated ordered report.
-- **Quality**: Business-first severity; secondary findings separated unless they also block an acceptance criterion; subagent reports stay strictly within their assigned skill’s scope.
-- **Output**: Ordered list: business gaps → edge cases → security → code review → passing summary → residual uncertainty.
-
-## Scope resolution
-
-**Chain-of-thought:** Before **`Workflow`**, answer **`Pause →`** for the governing spec you will use; equally plausible paths without disambiguation ⇒ **stop**.
-
-**User-named path** — Read `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, and batch `coordination.md` when present unless the user narrowed the list. Treat as authoritative unless the user pointed at a **newer** superseding plan. Map implementation via tasks, owned paths, diff, branch, commits.
-   - **Pause →** Did the user give a **filesystem path** or only a nickname that could map to multiple `docs/plans/...` trees?
-   - **Pause →** For each major business verdict later, what **exact** spec heading or requirement ID will I cite?
-
-**User did not name a spec** — Inspect `git status -sb`, `git diff --name-only`, `git diff --cached --name-only`; search `docs/plans/`, `docs/archive/plans/`, or repo-documented plan dirs. If no plan file moved, infer from recent commits and plausible plan dirs; **if still ambiguous, stop** (see Non-negotiables).
-   - **Pause →** What **three** independent clues tie this implementation to **one** plan—not chat memory alone?
-   - **Pause →** If I withheld the conversation transcript, could another reviewer replicate my chosen spec folder from repo evidence?
-
-## Workflow
-
-**Chain-of-thought:** Answer **`Pause →`** after **each** step before moving down the list or calling dependent skills.
-
-1. **Spec baseline** — Read governing docs end-to-end. Extract goals, acceptance criteria, non-goals, deferrals, required verifications. Build a compact claim list provable from repo evidence. Keep “what the product must do” separate from “how clean the code is.”
-   - **Pause →** Which items are **mandatory** acceptance vs explicitly **out of scope** or deferred?
-   - **Pause →** What observable failure would make me change a `Met` to `Not met` for the top risk requirement?
-
-2. **Implementation evidence** — Read the relevant diff/staged/commits/files. Trace the minimum code path to validate claims. Run spec-named checks when available and safe. When the spec contains **independent requirement clusters** (disjoint owned paths, disjoint spec sections), **MAY** dispatch one read-only subagent per cluster to score Met/Partial/Not-met with cited evidence; the main agent reconciles cross-requirement effects and owns the final verdict ordering. Tightly coupled requirements stay on the main agent.
-   - **Pause →** What is the **smallest** code path I have not yet read that could still falsify a `Met`?
-   - **Pause →** Am I about to score `Met` from **intent** or from **tests/commands** I actually ran or inspected?
-   - **Pause →** If I clustered, is every cluster genuinely disjoint, or am I about to lose a cross-requirement contradiction by running them in isolation?
-
-3. **Business-goal verdict first** — Emit every `Not met` / `Partially met` **before** secondary findings, with **exact** spec cites and code/test evidence. While required goals stay failed, **MUST NOT** frame archival, release, or “done” narratives that imply compliance.
-   - **Pause →** If I sorted findings by “interesting” instead of business impact, which line would unfairly rise above a missing goal?
-   - **Pause →** For each `Partially met`, what single **missing proof** (test, wire-up, error path) am I naming explicitly?
-
-4. **Secondary reviews (code-affecting)** — On the same scope: `review-change-set` (architecture/simplification), `discover-edge-cases` (reproducible edge/observability risks), `discover-security-issues` (reproducible security). **Prefer dispatching one read-only subagent per skill in parallel** so each runs in its own context with the full SKILL.md it owns; hand each subagent the same diff scope and the structured-report contract from that skill. The main agent waits for every subagent to return, then keeps outputs labeled so they do not read as business-goal substitutions. Trivial single-file diffs may run inline without subagents. The main agent **MUST NOT** re-run a secondary skill it already delegated, and subagents **MUST NOT** mutate the repository.
-   - **Pause →** Does this secondary finding **force** a business re-score—if yes, did I revise step 3 before publishing?
-   - **Pause →** Is the diff scope identical to what I used for business mapping (no silent file creep)?
-   - **Pause →** Did every dispatched secondary subagent return — or am I about to publish from partial summaries?
-
-5. **Final report (fixed order)** — (1) Business-goal failures (always top severity for required gaps). (2) Edge-case. (3) Security. (4) Code-review / maintainability. (5) Passing evidence for goals confirmed `Met`. (6) Residual uncertainty (skipped commands, unmapped spec text, unverifiable externals). If nothing actionable: state that explicitly **and** still cite docs and evidence reviewed.
-   - **Pause →** What commands or spec paragraphs remain **unverified**—are they all listed under residual uncertainty?
-
-## Sample hints
-
-- **Business claim record**:
-  - `R3.2 refresh token rotation` → `Not met` — spec `spec.md` §3.2 requires one-time use; `src/auth/refresh.rs:40` still accepts same jti on replay; test `refresh_replay` not present.
-- **Wrong ordering** — starting with “nice simplification in `foo.ts`” while `R1.0` is unmet: **wrong**; lead with the `R1.0` gap.
-- **Tasks checked but behavior missing** — `tasks.md` shows `[x] implement rate limit` but no call site in `src/api/*` and no test: verdict stays **`Not met` / `Partially met`**, not `Met`.
-- **Ambiguous scope** — two directories `docs/plans/2026-05-01/foo/` and `…/batch-a/foo/` both plausible; **stop** with “need user to name path” instead of picking one.
+## 目標
+輸出一份只讀的spec合規審查報告，先回答「這次變更是否真的滿足規劃中的業務要求」，再補充邊界、安全與代碼審查發現。報告需要對每條關鍵需求給出可追溯的狀態判定、證據來源、缺口說明、通過證據與剩餘不確定性；本技能不負責修改代碼或更新規劃文件。
+
+## 驗收條件
+- 在給出任何合規結論前，已唯一確定 governing spec；若存在兩個同樣合理的規劃根目錄且無法由倉庫證據消歧，必須停止並報告歧義，不能猜測。
+- 每條業務目標或驗收項只能根據可驗證證據判定為 `Met`、`Partially met`、`Not met` 或 `Deferred/N/A`；證據可來自代碼、測試、命令、日誌或追蹤，`tasks.md` 勾選本身不算證據。
+- 未滿足或部分滿足的必選業務要求永遠是最高嚴重度，報告排序中不得被安全、邊界或可維護性意見壓過。
+- 若範圍涉及代碼實作，完成業務結論後必須在同一範圍追加 `review-change-set`、`discover-edge-cases` 與 `discover-security-issues`；任一依賴不可用時，不得輸出「完整通過」結論。
+- 全流程保持只讀：不得修改實作、測試、spec、archive、commit、push、tag 或 release。
+- 最終交付物固定按以下順序輸出：業務缺口 → 邊界情況 → 安全問題 → 代碼審查問題 → 已滿足要求的通過證據 → 剩餘不確定性。
+
+## 工作流程
+1. 確定 governing spec。
+   - 若使用者已指定具體路徑，直接以該規劃目錄為準，閱讀 `spec.md`、`tasks.md`、`checklist.md`、`contract.md`、`design.md`，以及存在時的 `coordination.md`。
+   - 若使用者未指定，需根據 `git status`、diff、相關路徑、近期提交與計劃目錄證據回推出唯一 spec；若仍有歧義，立即停止。
+2. 建立spec基線。
+   - 從 governing spec 中抽取業務目標、驗收條件、非目標、已明示的延期項與要求執行的驗證。
+   - 將「產品必須做到什麼」和「代碼寫得是否漂亮」明確分開。
+3. 蒐集實作證據並先做業務判定。
+   - 閱讀最小必要代碼路徑、相關 diff、提交與測試，必要時執行 spec 點名且安全可跑的驗證命令。
+   - 對每條需求給出 `Met`、`Partially met`、`Not met` 或 `Deferred/N/A`，並附上精確 spec 引用與代碼/測試證據。
+   - 若 spec 中存在完全獨立的需求群組，可用只讀 subagent 並行評分；但最終排序、嚴重度與跨需求衝突整理由主代理負責。
+4. 對代碼範圍追加次級審查。
+   - 若審查對象包含代碼實作，必須在同一範圍追加 `review-change-set`、`discover-edge-cases` 與 `discover-security-issues`。
+   - 優先以一個只讀 subagent 對應一個次級技能並行執行，主代理只負責聚合結果，不重跑已委派分析。
+   - 若次級審查結果反過來影響某條業務需求的判定，必須先回寫業務結論，再輸出最終報告。
+5. 生成固定順序的最終報告。
+   - 先列出 `Not met` 與 `Partially met` 的業務缺口，再依序列出邊界情況、安全問題、代碼審查問題。
+   - 接著補上所有已確認 `Met` 的通過證據。
+   - 最後列出未驗證命令、無法映射的 spec 段落、外部依賴不可驗證處與其他剩餘不確定性。
+
+## 使用範例
+- 「這個 PR 有沒有滿足 `coordination.md` 和 `spec.md`？」-> 先唯一確定 governing spec，再按業務要求逐條打分，最後補上同範圍的邊界、安全與變更集審查。
+- 「請檢查 `docs/plans/2026-05-01/foo/` 對應的實作是否完成」-> 直接以指定目錄為準做只讀合規審查，不依賴聊天上下文猜測。
+- 「`tasks.md` 都打勾了，應該算完成吧？」-> 不能直接採信，仍需用代碼、測試、命令或追蹤證據重新驗證每條要求。
+- 「先跟我講哪個 requirement 沒達成，再看程式碼好不好」-> 報告必須先輸出業務缺口，不能先用重構或風格意見掩蓋未滿足的spec要求。
+
+## 參考資料索引
+- `review-change-set`：在相同代碼範圍上補做架構與簡化審查，避免將spec合規與代碼品質混為一談。
+- `discover-edge-cases`：在相同範圍上補做可重現邊界情況審查，補齊失敗路徑、併發與可觀測性風險。
+- `discover-security-issues`：在相同範圍上補做可重現安全審查，補齊攻擊面、授權與資料外洩風險。

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,91 +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 **`apltk architecture --help`**. Keep the meaning in this skill, but take the exact verbs, subverbs, and flags from the CLI itself.
-- **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** the cross-feature seams through `apltk architecture ... --spec <spec_dir>`, then renders and validates the overlay.
-
-- **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