@laitszkin/apollo-toolkit 3.11.7 → 3.12.0

package/test-case-strategy/SKILL.md

@@ -1,103 +1,56 @@
 ---
 name: test-case-strategy
-description: Select and design risk-driven test cases for agent implementation work. Use when specs, new-feature work, brownfield feature changes, refactors, or bug fixes need a concrete decision about unit, regression, property-based, integration, E2E, adversarial, mock/fake, or drift-check coverage.
+description: >-
+  為實作工作選擇最小且足夠的測試組合。當 spec、功能開發、功能增強、重構或 bug 修復
+  需要明確決定單元、回歸、property、integration、E2E、對抗性測試或 drift check 時使用。
 ---
 
-# Test Case Strategy
+# 測試案例策略
 
-## Standards
-
-- Evidence: Base every test decision on changed behavior, requirement IDs, risk class, dependency shape, and existing coverage; do not add tests only because a template lists them.
-- Execution: Choose the smallest test level that can prove the risk, then escalate to broader tests only when lower-level tests cannot observe the behavior or contract.
-- Quality: Each test must have a meaningful oracle derived from the requirement, design, or contract rather than from the implementation just written.
-- Output: Return concrete test case IDs, test level, target unit or flow, oracle, fixture/mock strategy, command or verification hook, and any `N/A` reason.
-
-## Goal
-
-Provide one shared testing decision workflow for spec generation and implementation skills so agents select useful tests consistently and use fast focused checks to detect implementation drift.
+## Dependencies
 
-## Workflow
+- Required: 無
+- Conditional: 無
+- Optional: 無
+- Fallback: 無
 
-### 1) Build the risk inventory
-
-- Identify changed behaviors, requirement IDs, and affected modules.
-- Classify risks before choosing test types:
-  - boundary
-  - regression
-  - authorization or permission denial
-  - invalid transition
-  - idempotency, replay, or duplicate submission
-  - concurrency or race
-  - data integrity
-  - external failure or inconsistent dependency state
-  - partial write, rollback, or compensation
-  - adversarial abuse
-- Reuse existing coverage only after naming the exact suite, test case, and risk it already proves.
-
-### 2) Choose the narrowest valid test level
-
-- Use unit tests for isolated changed logic, boundaries, denials, exact errors, no-side-effect expectations, and fast implementation drift checks.
-- Use regression tests when a bug-prone or historically fragile behavior must not silently return.
-- Use property-based tests for business rules with describable invariants, generated input spaces, valid/invalid state transitions, or external-state matrices that can be mocked.
-- Use integration tests for cross-module chains, repository/service/API/event interactions, configuration wiring, persistence, IO, and controlled external-service scenarios.
-- Use E2E tests only for critical user-visible paths whose risk is not sufficiently proven by lower-level tests; keep them minimal and stable.
-- Use adversarial tests for malformed input, forged identities, invalid transitions, replay, stale/out-of-order events, toxic payload sizes, and risky edge combinations.
-- If E2E is too costly or unstable, replace it with integration coverage for the same risk and record the replacement.
+## Standards
 
-### 3) Define the oracle before implementation
+- Evidence: 只根據需求、風險、受影響模組、依賴形態與現有覆蓋情況選擇測試，不為了湊數加測試
+- Execution: 先盤點風險與 oracle，再選最小可證明風險的測試層級，必要時才升級到更重的測試
+- Quality: 每個測試都要有可重現、可驗證的明確 oracle，而不是從新寫出的實作反推
+- Output: 產出可直接執行的測試決策，包含測試 ID、目標、層級、oracle、fixture/mock 策略、驗證命令與 `N/A` 理由
 
-- Derive expected behavior from `spec.md`, `design.md`, `contract.md`, official documentation, or existing intended behavior.
-- Never derive the oracle from the new implementation after writing it.
-- Prefer exact assertions:
-  - exact output
-  - exact error class or denial reason
-  - persisted state
-  - emitted event
-  - retry or compensation accounting
-  - intentional absence of writes, notifications, or side effects
-  - allowed state transition or rejection
-- Avoid assertion-light smoke tests, snapshot-only tests, and tests that only prove "does not throw" unless that is the real requirement.
+## 技能目標
 
-### 4) Add unit drift checks for atomic implementation tasks
+提供一套統一的測試決策流程，讓spec技能與實作技能都能用一致的方法挑出高價值測試，並用最快、最聚焦的檢查及早發現實作偏移。
 
-- For each non-trivial atomic task, decide whether a focused unit drift check is possible.
-- A unit drift check should name:
-  - target unit: function, method, module, policy, parser, mapper, validator, or state transition owner
-  - input state: minimal fixture, table row, fake dependency state, or boundary value
-  - oracle: exact output, error, state change, or no-side-effect assertion
-  - command: focused test command or existing test filter to run immediately after the task
-- If no unit drift check is possible, record the smallest replacement check and a concrete reason.
-- Do not allow broad integration or E2E tests to hide missing unit checks for locally owned business logic.
+## 驗收條件
 
-### 5) Record the decision
+- 每個非平凡變更都已建立風險清單，並明確指出需求或風險來源
+- 每個測試決策都選擇了最小但足以證明風險的測試層級，而不是預設往大測試堆
+- 每個測試都有明確 oracle、fixture 或 mock 策略，以及可執行的驗證方式
+- 若某種測試層級不適用，已留下具體 `N/A` 理由而非含糊跳過
 
-Use this compact record in planning docs or implementation summaries:
+## 工作流程
 
-```text
-Test ID: UT-01 / REG-01 / PBT-01 / IT-01 / E2E-01 / ADV-01
-Requirement/Risk: R?.? / boundary | regression | ...
-Target: function/module/flow
-Fixture or mock strategy: ...
-Oracle: exact output/error/state/no-side-effect
-Verification hook: command or existing suite
-N/A reason: only when this test level is not suitable
-```
+1. 先盤點變更行為、需求編號、受影響模組與風險，至少涵蓋 boundary、regression、authorization、invalid transition、idempotency、concurrency、data integrity、external failure、partial write 與 adversarial abuse
+2. 先重用現有測試，再決定新增哪些測試；只有在能說出既有 suite、case 與它覆蓋的風險時，才算真的能重用
+3. 依風險選擇最窄的有效測試層級：局部邏輯用 unit 或 regression；可描述不變量的邏輯用 property；跨模組與受控外部狀態用 integration；只有在關鍵使用者流程無法被較低層級證明時才使用 E2E；惡意輸入、重播、偽造、越界與異常組合用 adversarial
+4. 在實作前先定義 oracle，來源只能是 `spec.md`、`design.md`、`contract.md`、官方文件或既有正確行為，不能從新實作反推
+5. 對每個非平凡原子任務補上 unit drift check；若做不到，必須記錄最小替代檢查與具體原因
+6. 用統一格式記錄測試決策，讓後續技能可以直接執行與驗證
 
-## Working Rules
+## 使用範例
 
-- Start from risk and oracle, not from a desired test count.
-- Prefer fast focused tests for implementation drift detection.
-- Keep one test focused on one behavior or one failure mode.
-- Use table-driven unit tests when many discrete business cases share one oracle.
-- Use mocks/fakes for external services in business logic chains unless the real external contract itself is under test.
-- Keep fixtures reproducible with fixed clocks, seeds, and controlled dependency states.
-- Preserve failing generated examples or seeds as regression coverage.
-- Record `N/A` only with a concrete reason tied to scope, risk, or observability.
-- When a spec exists, map test IDs back to `tasks.md` and `checklist.md`.
+- 「修改驗證器的邊界規則」-> 優先選 unit test，加一個 drift check 驗證邊界值、錯誤類型與無副作用
+- 「新增排序與去重邏輯」-> 使用 property-based tests 驗證單調性、資料保留與重播不變量
+- 「改動 repository、service 與 API handler 的協作」-> 使用 integration tests 驗證跨模組資料流與錯誤處理
+- 「高價值結帳流程可能被權限與狀態機影響」-> 僅在 unit / integration 不足以證明風險時才加最小 E2E
 
-## References
+## 參考資料索引
 
-- `references/unit-tests.md`: unit test and drift-check design.
-- `references/property-based-tests.md`: property-based test selection and oracle design.
-- `references/integration-tests.md`: integration test selection and external-state scenarios.
-- `references/e2e-tests.md`: E2E decision and replacement rules.
+- `references/unit-tests.md`：單元測試與 drift check 設計
+- `references/property-based-tests.md`：property tests 的選擇與 oracle 設計
+- `references/integration-tests.md`：整合測試與外部狀態場景設計
+- `references/e2e-tests.md`：E2E 決策與替代規則

package/update-project-html/SKILL.md

@@ -1,125 +1,40 @@
 ---
 name: update-project-html
 description: >-
-  Refresh the base project HTML architecture atlas to reflect the latest code changes: read the existing atlas, resolve diff scope (`git diff --stat` + staged by default, or `git diff --stat <base>..HEAD` when a ref is named), filter to code-affecting hunks, and update affected feature/sub-module declarations through `apltk architecture` (no `--spec` — base atlas, not spec overlays). **Subagents only:** dispatch ONE write-capable subagent per affected feature; each deep-reads only its own changed files, applies every intra-feature delta (function/variable/dataflow/error/intra-feature edge add|set|remove|reorder), and returns ONLY (i) sub-module change summary and (ii) outbound boundary deltas. The main agent waits until every subagent finishes before declaring cross-feature edges, then `apltk architecture render` + `validate`. Exact CLI: `apltk architecture --help`. Anchor every change to the actual diff. For unshipped spec work use `spec-to-project-html`; first-time bootstrap use `init-project-html`.
+  使用 `apltk architecture` 按真實程式碼 diff 刷新基礎專案 HTML 架構圖譜。先確定 diff 範圍並過濾出真正影響執行時行為的變更，再按受影響功能分派可寫子 agent 處理功能內更新；主 agent 必須等待全部子 agent 完成後，才能補跨功能邊並執行 `render` 與 `validate`。該技能只更新基礎 atlas，不使用 `--spec`。
 ---
 
-# Update Project HTML
+# 更新專案 HTML 架構圖
 
-## Dependencies
+## 技能目標
 
-- Required: **`init-project-html`** — its `SKILL.md` is the semantic rulebook (acceptance criteria, two-layer rule, `edge.kind` enum, function/variable referencing rules); **`apltk architecture --help`** is the verb/flag source of truth.
-- Conditional: **`spec-to-project-html`** when the user actually wants an overlay scoped to a `docs/plans/...` spec rather than the base atlas — that skill uses `--spec`.
-- Optional: **`align-project-documents`** when feature names in the atlas no longer match the `docs/features` set after the diff.
-- Fallback: changed code references components that are absent from the atlas → declare new sub-modules / functions / variables before referencing them; if a single feature’s diff is too large for one subagent context, split that feature’s subagent by sub-module folder. **MUST NOT** invent components for code paths that were never read.
+根據目前分支、工作區或指定提交範圍內的真實程式碼變更，增量刷新 `resources/project-architecture/` 下的基礎 atlas 與渲染 HTML，使圖譜持續和實際程式碼保持一致。
 
-## Non-negotiables
+## 驗收條件
 
-- **MUST** mutate atlas state only through the CLI (`apltk architecture …`). The renderer owns `resources/project-architecture/**/*.html` — agents **MUST NOT** hand-edit those files.
-- **MUST** target the **base atlas** (no `--spec` flag). This skill is for code that has *already shipped* (or is about to be committed) and therefore belongs in the canonical diagram. For planned/unmerged work scoped to a spec, redirect to **`spec-to-project-html`**. For repos with no atlas yet, redirect to **`init-project-html`**.
-- **MUST** decide the diff scope **before** reading any source files: working tree (`git diff --stat`) + staged (`git diff --cached --stat`) by default; an explicit ref/range when the user names one (e.g. `git diff --stat $(git merge-base HEAD origin/main)..HEAD` for a PR refresh). Print the literal command(s) you ran in the report so the run is reproducible.
-- **MUST** filter to **code-affecting** hunks — exclude pure docs/markdown/asset edits, generated files, lockfiles, and formatting-only diffs that do not change runtime behavior. Record skipped buckets in the report so reviewers can audit the filter.
-- **MUST** preserve the existing atlas structure for parts the diff did not touch — never delete features, sub-modules, or edges just because the current diff is silent about them. Only mutate what the diff actually changed (rename, move, remove, add, behavior change).
-- **MUST** use the **subagent fan-out** pattern from `init-project-html` Rule 3:
-  1. Enumerate **affected features** from the filtered diff (path → feature mapping using existing atlas YAML + folder layout). No function-body deep reads at this stage.
-  2. Dispatch **one write-capable subagent per affected feature**. Each deep-reads only its own changed files (use `git diff` for exact deltas plus the post-change source for context), applies every intra-feature mutation via `apltk architecture` (`function`, `variable`, `dataflow`, `error`, intra-feature `edge` add|set|remove|reorder), and returns ONLY (i) sub-module change summary and (ii) outbound boundary deltas (cross-feature edges to add/change/remove with endpoints + suggested kind/label).
-  3. **HARD GATE:** the main agent **MUST** wait until **every** dispatched subagent has finished (success or explicit failure report) before declaring any cross-feature `edge`, shared `meta` that stitches multiple features, or `actor` that exists only for cross-feature context.
-- **MUST** run `apltk architecture render` (when subagents batched with `--no-render`) and `apltk architecture validate` after the cross-feature wiring; resolve every reported error before reporting completion.
-- **MUST NOT** re-read source for a delegated feature in the main agent and **MUST NOT** re-declare intra-feature components a subagent already owns.
-- **MUST NOT** generate spec overlay artifacts (`<spec_dir>/architecture_diff/atlas/`) — that is **`spec-to-project-html`**’s job.
+- 只透過 `apltk architecture` 更新基礎 atlas；不得手改 `resources/project-architecture/**/*.html`，也不得寫入任何 `--spec` overlay 產物。
+- 在讀取原始碼前就明確本次 diff 範圍，並在報告中保留所執行的原始命令；過濾掉純文件、靜態資源、鎖檔、生成物和純格式化變更，同時記錄被跳過的類別與原因。
+- 選定範圍內每個真正影響行為的 hunk，都要麼體現在功能內元件更新或跨功能邊變化上，要麼在交付報告中明確標註「對圖譜無影響」及原因。
+- 按「每個受影響功能一個可寫子 agent」執行；主 agent 必須等全部子 agent 完成後，才允許修改跨功能 `edge`、共享 `meta` 或補充跨功能上下文。
+- 更新後的圖譜繼續滿足 `init-project-html` 的語義要求，且 `apltk architecture validate` 通過。
 
-## Standards (summary)
+## 工作流程
 
-- **Evidence**: every CLI mutation traces to a specific file + diff hunk; record the chosen diff scope and skipped buckets in `meta.summary` via the CLI.
-- **Execution**: read base atlas → resolve diff scope → filter to code-affecting hunks → map paths to features → subagent fan-out → wait for all → cross-feature edges → `render` → `validate` → handover.
-- **Quality**: macro SVG still reflects every cross-feature data-row that exists in the *new* code; sub-module declarations stay self-only; `apltk architecture validate` returns OK.
-- **Output**: updated `resources/project-architecture/atlas/**/*.yaml` + re-rendered `resources/project-architecture/**/*.html` + a report listing affected features, mutation counts, skipped diff buckets, and the `validate` outcome.
+1. 先確認基礎 atlas 已存在，並執行 `apltk architecture --help` 取得最新 CLI 用法；如果倉庫還沒有 atlas，改用 `init-project-html`；如果需求針對規劃文件 overlay，改用 `spec-to-project-html`。
+2. 在讀取原始碼前先決定 diff 範圍。預設同時檢查未暫存與已暫存改動；若使用者明確指定基線、提交或區間，則按使用者指定範圍執行。
+3. 僅保留真正影響程式碼行為的變更，並把這些路徑映射到受影響功能；此階段只做結構映射，不深讀函式實作。
+4. 為每個受影響功能派發一個可寫子 agent。每個子 agent 只讀取自己負責功能的現有 atlas 與變更檔案，完成全部功能內更新：子模組、函式、變數、資料流、錯誤以及功能內邊，並返回子模組變更摘要與跨功能邊界增量。
+5. 主 agent 不得重讀已委派功能的原始碼，也不得重複宣告子 agent 已處理的功能內元件；只能在全部子 agent 完成後，統一補跨功能邊、必要的共享 `meta`，再執行 `apltk architecture render` 與 `apltk architecture validate`。
+6. 最終報告至少包含：diff 範圍命令、受影響功能列表、各功能更新摘要、跨功能邊變化、被跳過的 diff 類別及原因、驗證結果，以及渲染輸出位置。
 
-## Acceptance criteria
+## 使用範例
 
-The atlas update is only complete when **all** of the following hold:
+- 「把目前分支的程式碼變化同步到基礎架構圖。」 -> 「按分支 diff 識別受影響功能，分別更新功能內宣告，再統一補跨功能連接並重新渲染。」
+- 「刷新這次 PR 的專案 HTML atlas。」 -> 「先鎖定 PR 的 diff 基線，再僅處理有執行時影響的變更，避免無關文件改動污染圖譜。」
 
-1. Every code-affecting hunk in the chosen diff scope is reflected in either an intra-feature mutation (function/variable/dataflow/error/edge) or a cross-feature edge — or is explicitly listed under "no diagram impact" in the handover report with a one-line reason.
-2. `apltk architecture validate` returns OK.
-3. Macro acceptance criteria from `init-project-html` still hold: cross-boundary interaction expressed as `call`/`return`/`data-row`/`failure` edges (never sub-module page prose); each touched sub-module’s internal diagram has function-to-function flow plus declared variable reads/writes for non-trivial steps.
-4. The handover report cites: chosen diff scope (literal commands), affected feature list, per-feature mutation counts, skipped diff buckets (with reasons), and confirmation that **all subagents completed before cross-feature wiring**.
+## 參考資料索引
 
-## How to use `apltk architecture`
-
-**Authoritative command tree:** run **`apltk architecture --help`** (same output as `apltk architecture help`). Same families as `init-project-html`:
-
-- `feature` / `submodule` — structural mutations (use **`set`** for label/role updates, **`remove`** when code deleted the entry point, **`add`** when the diff introduced a new module).
-- `function` / `variable` / `dataflow` / `error` — per-sub-module rows. Declare new symbols **before** referencing them in `dataflow`. Use the row-level `remove` (see `--help`) to delete obsolete rows the diff dropped.
-- `edge` — intra- or cross-feature seams. Prefer stable **`--id`** when re-applying the same edge after a mutation cycle. `kind` ∈ `call` | `return` | `data-row` | `failure`.
-- `meta` / `actor` — only when the diff actually changed the macro narrative (e.g. summary now needs to record the diff scope or new omissions).
-- `render` (when you batched with `--no-render`) → `validate` → done.
-
-This skill **never** uses `--spec`. If the user wants overlay diagrams for a planning doc, redirect to **`spec-to-project-html`**.
-
-## Workflow
-
-**Chain-of-thought:** Answer **`Pause →`** before moving on. Validator red **MUST** block "done."
-
-### 1) Read the current atlas (no source code yet)
-
-- Open `resources/project-architecture/index.html` to confirm the atlas exists and renders. If it does not, redirect to **`init-project-html`** — this skill is for refreshes, not bootstraps.
-- List `resources/project-architecture/atlas/atlas.index.yaml` and the per-feature YAMLs to learn the current feature set, sub-modules, and edge ids.
-   - **Pause →** Do I actually have a base atlas to update? If not — stop and route to **`init-project-html`**.
-
-### 2) Resolve diff scope
-
-- Default: **uncommitted** (`git diff --stat`) + **staged** (`git diff --cached --stat`); show both. If the user pointed at a ref/range/commit, use that instead (`git diff --stat <base>..HEAD`, `git diff --stat HEAD~N`, `git show --stat <sha>`, etc.).
-- Print the chosen diff scope as the literal command(s) you ran so the report is reproducible.
-   - **Pause →** Is this the diff the user actually meant — or am I about to refresh the atlas against the wrong baseline?
-
-### 3) Filter to code-affecting changes
-
-- Drop pure docs/markdown/assets/lockfiles/generated/format-only diffs. Keep source files in language directories the project actually treats as code (open the project layout if uncertain).
-- Group remaining files into **affected features** using the per-feature YAML’s declared paths plus folder/package heuristics. Record the path → feature mapping.
-   - **Pause →** Did I drop a hunk that actually changes runtime behavior (e.g. a config file the runtime reads)? Re-include if so.
-   - **Pause →** Are there changed files I cannot map to any existing feature — do they create a new feature, or do they extend an existing one? Decide explicitly before delegating.
-
-### 4) Subagent fan-out — workers own features; orchestrator owns cross-feature seams **after** all workers finish
-
-Dispatch one **write-capable** subagent per affected feature. Hand each subagent: its feature slug, the list of changed files in that feature, the diff scope command(s), the existing feature-module list (so it knows other features’ slugs for outbound edges), and **`apltk architecture --help`** as the flag reference.
-
-> **Feature `<slug>` subagent contract**
-> - Read the existing per-feature YAML and every changed file in this feature E2E (with `git diff` for the exact delta plus the post-change source for context).
-> - For every behavior change in this feature, apply the matching CLI mutation: structural (`feature` / `submodule`), rows (`function`, `variable`, `dataflow`, `error`), and intra-feature **`edge`** add/set/remove/reorder.
-> - Declare new functions / variables **before** referencing them from `dataflow`.
-> - Run **`apltk architecture validate`** before returning.
-> - **Return ONLY**: (i) sub-module change list (slug + change kind + one-line reason) and (ii) outbound boundary deltas (cross-feature edges to add/change/remove with endpoints + suggested kind/label). No source dumps.
-
-**Orchestrator — after every subagent has completed:**
-
-```bash
-# only when meta.summary needs to record the diff scope or new omissions
-apltk architecture meta set --summary "..." --no-render
-# one edge mutation per cross-feature interaction reported by the subagents
-apltk architecture edge add --from <featA>/<subA> --to <featB>/<subB> --kind call|return|data-row|failure --label "..." --no-render
-apltk architecture edge remove --id <stable_id> --no-render
-apltk architecture render
-apltk architecture validate
-```
-
-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 →** Did every subagent return — or am I about to wire cross-feature edges from partial summaries?
-
-### 5) Handover report
-
-Report: chosen diff scope (literal commands), affected features (count), per-feature mutation summary, cross-feature edge deltas (added / removed / changed), skipped diff buckets (with reasons), `validate` outcome, and the location of the rendered atlas (`resources/project-architecture/index.html`).
-
-## Sample hints
-
-- **Renamed function**: subagent removes the old `function` row, adds the new one, and updates every `dataflow` step that referenced it — do **not** silently leave the old row.
-- **Deleted sub-module**: subagent uses `submodule remove` (see `--help`) and reports the outbound edges to drop; the orchestrator removes the cross-feature edges by stable `--id` after the gate.
-- **New cross-feature data-row**: only one subagent will see the producing side and another only the consumer side — both subagents flag it as an outbound boundary; the orchestrator declares the single `data-row` edge **after** the gate.
-- **Pure formatting diff**: skip entirely; record under "no diagram impact" in the report so future runs do not re-litigate the file.
-- **PR refresh against `main`**: when the user asks to refresh the atlas to reflect "everything on this branch", use `git diff --stat $(git merge-base HEAD origin/main)..HEAD` and state the resolved base SHA in the report.
-
-## References
-
-- **`init-project-html/SKILL.md`** — semantic rulebook, two-layer rule, acceptance criteria, full subagent contract.
-- **`init-project-html/references/TEMPLATE_SPEC.md`** — schema cheat sheet (fields/enums).
-- **`spec-to-project-html/SKILL.md`** — overlay flow when work is still in spec form.
-- **`apltk architecture --help`** — live CLI reference; trust this over any prose.
+- `init-project-html/SKILL.md`：基礎 atlas 的語義規則、子模組表達約束與總體驗收標準。
+- `spec-to-project-html/SKILL.md`：當需求針對 `docs/plans/...` overlay 而非基礎 atlas 時使用。
+- `README.md`：本技能的簡要用途說明。
+- `apltk architecture --help`：命令、參數和子命令的唯一真源。

package/version-release/SKILL.md

@@ -1,94 +1,59 @@
 ---
 name: version-release
 description: >-
-  End-to-end semver delivery: prerequisites mirror **`commit-and-push`** gates (**`submission-readiness-check`**, reviews, changelog hygiene, optional `archive-specs`), derive next version/tag from tracked files plus explicit user semver words, relocate `CHANGELOG.md` Unreleased into dated release bump package/project metadata evenly commit tag push **`gh release create`** honoring prerelease/retarget rules verify remote refs **NEVER STOP at tag omitting GitHub release unless user waived publication**.
-  Keywords patch minor major release tag GH publish semver… misroute plain “push” absent release vocabulary **use commit-and-push**… BAD guessing version… GOOD inspect package.json+Cargo.toml… retarget prerelease relocate tag `--force-with-lease`… Unreleased emptiness ⇒ halt curated notes…
+  用於明確的 semver 發版流程。必須先完成 `commit-and-push` 共用 gate 與
+  `submission-readiness-check`，再決定版本、更新 changelog、建立 tag、推送並發布 GitHub Release。
 ---
 
-# Version Release
+# 版本發佈
 
 ## Dependencies
 
-- Required: **`commit-and-push`** (shared inspect/classify/readiness/commit/push mechanics); **`submission-readiness-check`** **before** version files, tags, or publication mutate.
-- Conditional: **`archive-specs`** when specs/docs need alignment; **`review-change-set`** on **code-affecting** release scope **before** version churn—blocking while findings open.
-- Optional: none.
-- Fallback: Missing required skill ⇒ stop and report.
+- Required: `commit-and-push`、`submission-readiness-check`
+- Conditional: `review-change-set`、`archive-specs`
+- Optional: 無
+- Fallback: 缺少必需技能時必須停止，不能憑印象手動補一個發版流程
 
-## Non-negotiables
+## Standards
 
-- **ONLY** enter this workflow when release intent is **explicit** (semver bump wording, tag/release request, CI “publish release”—not a bare “push”). Else **`commit-and-push`** only.
-- **MUST NOT** guess versions—read workspace version files + user-stated bump; state **current → next** + exact **tag string** before editing.
-- **MUST NOT** publish if root **`CHANGELOG.md` `Unreleased`** is empty/has nothing to ship—stop or curate notes first.
-- **MUST** align all version-bearing files consistently; formatting-only deltas elsewhere.
-- **Tag format** (`v1.2.3` vs `1.2.3`) inferred from repo history—not invented per release ad hoc unless user dictates.
-- **GitHub Release**: prefer `gh release create` / repo tooling; **MUST NOT** substitute “opened PR URL” as release completion. Draft vs prerelease vs **latest** follows **explicit** user/repo convention—not tag shape alone.
-- **Prerelease retarget**: same version, **move** tag/release to new SHA when user asks; use force-with-lease **for tag only** as needed; if API rejects SHA for `target_commitish`, use branch identifier per GitHub rules.
-- **MUST** verify **remote** has commit + tag before calling release **done**; **MUST NOT** trust UI git shortcuts.
-- **Done** = version files + changelog section + **pushed** commit + **remote** tag + **published** GitHub release (unless user explicitly skips publication—then say so).
+- Evidence: 以版本檔、`CHANGELOG.md`、本地/remote tag、既有 GitHub Release 與使用者明確的 bump 意圖作為依據
+- Execution: 先確認這真的是 release 請求，再完成所有 gate，之後才更新版本、切 changelog、打 tag、推送與發布 Release
+- Quality: 不猜版本、不重複發版、不用原始 diff 臨時拼 release notes；所有版本入口必須同步一致
+- Output: 交付可驗證的版本發佈結果，包含版本號、tag、remote驗證與 GitHub Release URL
 
-**Repository regression checks:** Before creating release metadata, inspect existing local and remote tags plus any existing GitHub Release for the target version so duplicates are caught early. Do not continue until you can state the current version, the intended next version, and the exact tag name that will be created. **`review-change-set` is required for code-affecting releases**—run `review-change-set` for the same release scope before continuing; treat unresolved review findings as blocking. Any conditional gate whose trigger is confirmed by this classification becomes mandatory before version bumping, tagging, or release publication. Treat every scenario-matched gate as blocking before versioning or release publication. Never stop after the release commit or tag alone; creating the matching GitHub release is part of done criteria unless the user explicitly says to skip release publication.
+## 技能目標
 
-## Standards (summary)
+把明確的發版需求轉成一條完整、可驗證、可追溯的 semver 流程，確保版本檔、changelog、git tag、remote狀態與 GitHub Release 彼此一致。
 
-- **Evidence**: Version files, tags local/remote, `Unreleased`, existing GH releases.
-- **Execution**: Intent → gates (`commit-and-push` pattern) → semver → files → changelog move → commit/tag → push → GH release.
-- **Quality**: No duplicate releases; notes from curated changelog, not raw diff guesswork.
-- **Output**: Announced version, tag URL, release URL, automation status if any.
+## 驗收條件
 
-## References
+- 已先確認這是明確的 release / semver 請求；若只是 commit 或 push，必須改走 `commit-and-push`
+- 在修改任何版本相關檔案前，已清楚說出 current -> next 版本與將建立的 tag 字串
+- `submission-readiness-check`、必要的 `review-change-set` 與 `archive-specs` 都已完成，且 `CHANGELOG.md` 的 `Unreleased` 內容足以支撐本次發版
+- 最終已同步版本檔、發布說明、commit、tag、remote refs 與 GitHub Release；若使用者明確要求不發布 Release，需在結果中清楚註明
 
-- `references/semantic-versioning.md`
-- `references/commit-messages.md`
-- `references/branch-naming.md`
-- `references/changelog-writing.md`
-- `references/readme-writing.md`
+## 工作流程
 
-## Workflow
+1. 先確認使用者是否真的要求 release、publish、tag、patch、minor、major 或其他明確 semver 動作；若沒有，改用 `commit-and-push`
+2. 檢查目前 git 狀態、版本檔、既有 tag、本地與remote是否已有同版本 tag，以及 GitHub 上是否已有同版本 Release，避免重複發版
+3. 對 code-affecting 範圍先完成 `review-change-set`，再執行 `submission-readiness-check`；若它要求 `archive-specs` 或 changelog/文件同步，必須先完成
+4. 根據版本檔、repo 歷史與使用者指示決定 current -> next 版本與 tag 格式；若語意不明，優先選較小 bump 並請使用者確認
+5. 一致更新所有版本入口，並把 `CHANGELOG.md` 的 `Unreleased` 移到新的版本區塊；release notes 只能來自整理過的 changelog 內容
+6. 建立 release commit 與 tag；若是 prerelease retarget，保留版本號不變，只把 tag / Release 移到新的 commit
+7. 推送分支與 tag，並驗證remote commit 與 tag 都已正確存在
+8. 使用 `gh release create` 或 repo 慣用工具建立或更新 GitHub Release，最後回報版本號、tag 與 release URL
 
-**Chain-of-thought:** Reuse **`commit-and-push`** for git inspection, classification, conditional reviews, **`submission-readiness-check`**, commit discipline, push verification—**do not duplicate** those rules here; **`Pause →`** applies to release-only decisions.
+## 使用範例
 
-### 1) Inspect git state
+- 「發 patch release」-> 先確認目前版本與 changelog，再更新到下一個 patch、建立 tag 並發布 Release
+- 「把 prerelease tag 移到最新修正」-> 不增加版本號，只重新對準 tag 與對應 Release
+- 「幫我 commit 然後 push」-> 不使用本技能，改走 `commit-and-push`
 
-- Follow **`commit-and-push`** step 1 (status/diff/clean semantics).
+## 參考資料索引
 
-### 2) Confirm release intent
-
-- Explicit semver/release language—or stop and use **`commit-and-push`**.
-   - **Pause →** Did the user only ask “commit”? If yes, **exit** this skill.
-
-### 3) Gates before version churn
-
-- Classify scope; code-affecting ⇒ `review-change-set`; **`submission-readiness-check`** (+ **`archive-specs`** when indicated). All blocking items closed.
-   - **Pause →** Am I versioning while `Unreleased`/readiness still wrong?
-
-### 4) Decide version & tag
-
-- Read files; inspect local/remote tags + existing GH release for collision; prerelease vs stable per user/doc; retarget flow leaves version unchanged.
-   - **Pause →** If tag+release already correct on intended SHA—report satisfied, duplicate nothing.
-
-### 5) Bump files
-
-- Every locator of version bumped consistently.
-
-### 6) Release docs
-
-- Move **`Unreleased`** → new dated heading; reset `Unreleased` scaffold; **`README`** / **`AGENTS.md`**/`CLAUDE.md` only if behavior/agent workflow changed materially.
-
-### 7) Commit & tag
-
-- Message e.g. `chore(release): publish X.Y.Z` per repo habit; tag after commit; retarget ⇒ move existing tag deliberately with hash discipline.
-
-### 8) Push
-
-- Push branch **and** tag; verify remote refs; retarget ⇒ `--force-with-lease` for tag only where appropriate, then verify.
-
-### 9) Publish GitHub Release
-
-- Create/update matching release body from changelog section; prerelease flag per explicit instruction; confirm non-draft unless automation needs draft—but user asked “publish” ⇒ actually publish.
-   - **Pause →** Can I paste **release URL** + prove tag points at **`HEAD`**?
-
-## Sample hints
-
-- **`Unreleased` empty** ⇒ cannot ship “2.5.0” with honest notes—curate first.
-- **Duplicate**: Tag `v2.5.0` exists on GH → **inspect SHA** before re-creating.
-- **Retarget**: User “move prerelease to latest fix”—**no** semver bump; rewrite tag carefully.
+- `references/semantic-versioning.md`：版本號選擇規則
+- `references/commit-messages.md`：release commit 訊息格式
+- `references/branch-naming.md`：分支命名慣例
+- `references/changelog-writing.md`：`CHANGELOG.md` 與 `Unreleased` 維護規則
+- `references/readme-writing.md`：README 只在必要時同步更新
+- `commit-and-push`：共享的 git 檢查、提交與推送 discipline

package/weekly-financial-event-report/scripts/extract_pdf_text_pdfkit.swift

@@ -3,6 +3,21 @@
 import Foundation
 import PDFKit
 
+let helpText = """
+apltk extract-pdf-text-pdfkit — extract PDF text with macOS PDFKit.
+
+Usage:
+  apltk extract-pdf-text-pdfkit /absolute/path/to/source.pdf
+  swift weekly-financial-event-report/scripts/extract_pdf_text_pdfkit.swift /absolute/path/to/source.pdf
+
+Use this when:
+  - You need a simple macOS PDFKit-based text extraction fallback.
+
+Examples:
+  apltk extract-pdf-text-pdfkit /absolute/path/to/source.pdf
+    Result: prints `PDF_PATH=...`, `PAGE_COUNT=...`, and one `=== PAGE N ===` section per extracted page.
+"""
+
 struct Arguments {
     let pdfPath: String
 }
@@ -15,7 +30,7 @@ enum ExtractionError: Error, CustomStringConvertible {
     var description: String {
         switch self {
         case .missingPath:
-            return "Usage: swift scripts/extract_pdf_text_pdfkit.swift /absolute/path/to/source.pdf"
+            return "Usage: swift scripts/extract_pdf_text_pdfkit.swift /absolute/path/to/source.pdf\nRun with --help for the full command guide."
         case .unsupportedPlatform:
             return "PDFKit extraction is only supported on macOS."
         case .unreadablePDF(let path):
@@ -24,19 +39,31 @@ enum ExtractionError: Error, CustomStringConvertible {
     }
 }
 
-func parseArguments() throws -> Arguments {
+enum ParseResult {
+    case help
+    case arguments(Arguments)
+}
+
+func parseArguments() throws -> ParseResult {
     let args = Array(CommandLine.arguments.dropFirst())
+    if args.contains("--help") || args.contains("-h") {
+        return .help
+    }
     guard let pdfPath = args.first, !pdfPath.isEmpty else {
         throw ExtractionError.missingPath
     }
-    return Arguments(pdfPath: pdfPath)
+    return .arguments(Arguments(pdfPath: pdfPath))
 }
 
 func main() throws {
     #if !os(macOS)
     throw ExtractionError.unsupportedPlatform
     #else
-    let arguments = try parseArguments()
+    switch try parseArguments() {
+    case .help:
+        print(helpText)
+        return
+    case .arguments(let arguments):
     let pdfURL = URL(fileURLWithPath: arguments.pdfPath)
 
     guard let document = PDFDocument(url: pdfURL) else {
@@ -60,6 +87,7 @@ func main() throws {
             print(text)
         }
     }
+    }
     #endif
 }
 

package/archive-specs/references/templates/architecture.md

@@ -1,21 +0,0 @@
-# <模組／層名稱> 設計原則
-
-[One-sentence summary of this module's role in the system.]
-
-## <原則標題>
-
-<原則描述：這條原則規範什麼、為什麼這樣設計、適用範圍>
-
-## <原則標題>
-
-<原則描述>
-
----
-
-## Writing Rules
-
-- State design principles, not implementation details.
-- Keep each principle macro-level so it survives minor code changes.
-- Focus on: module responsibilities, boundary rules, data flow direction, and integration contracts.
-- Each file covers one module or architectural layer.
-- Before writing a principle, ask: "Would a refactor that renames files or extracts a helper violate this principle?" If yes, the principle is too specific.

package/archive-specs/references/templates/docs-index.md

@@ -1,39 +0,0 @@
-# [Project Name] Documentation Index
-
-## Features (`docs/features/`)
-
-User-facing capabilities described with BDD scenarios (Given/When/Then). Each file covers one functional category.
-
-| File | Category | Description |
-| --- | --- | --- |
-| `docs/features/[category].md` | [category name] | [One-line description] |
-
-## Architecture (`docs/architecture/`)
-
-Macro-level design principles organized by module or layer. Each principle is abstract enough to survive minor code changes.
-
-| File | Module | Description |
-| --- | --- | --- |
-| `docs/architecture/[module].md` | [module name] | [One-line description] |
-
-## Principles (`docs/principles/`)
-
-Code style, naming conventions, and development constraints extracted from the codebase.
-
-| File | Topic | Description |
-| --- | --- | --- |
-| `docs/principles/[topic].md` | [topic name] | [One-line description] |
-
-## Root Documents
-
-- `README.md` — project overview and quick start
-- `CONTRIBUTING.md` — contribution workflow (if applicable)
-- `SECURITY.md` — vulnerability reporting (if applicable)
-- `CHANGELOG.md` — release history (if applicable)
-
-## Reference List
-
-- Source specs reviewed: [list of spec directories/files]
-- Existing docs updated: [paths]
-- Important code/config references: [paths]
-- Remaining unknowns: [list or `None`]

package/archive-specs/references/templates/features.md

@@ -1,25 +0,0 @@
-# <功能類別名稱>
-
-[One-sentence summary of this functional category from a user perspective.]
-
-## <功能名稱>
-
-- **Given** <前置條件>
-- **When** <使用者操作>
-- **Then** <預期結果>
-
-## <功能名稱>
-
-- **Given** <前置條件>
-- **When** <使用者操作>
-- **Then** <預期結果>
-
----
-
-## Writing Rules
-
-- Describe behavior from a user's perspective; never mention file paths, function names, or database tables.
-- Use BDD phrasing: **Given** (precondition) → **When** (action) → **Then** (outcome).
-- Each file covers exactly one functional category (e.g., authentication, data export, notifications).
-- Group related features under descriptive subheadings.
-- Title the file with a term users would recognize, not a module name.