@laitszkin/apollo-toolkit 3.8.3 → 3.8.4

package/CHANGELOG.md

@@ -34,6 +34,12 @@ All notable changes to this repository are documented in this file.
 ### Added
 - (None yet)
 
+## [v3.8.4] - 2026-05-04
+
+### Changed
+- Simplify `generate-spec` checklist template from 108 lines to 53 lines: consolidate multi-field behavior-to-test items into single-line checkboxes, flatten hardening records, and streamline E2E/integration decisions and completion records
+- Emphasize official documentation lookup as mandatory step in `generate-spec` workflow
+
 ## [v3.8.0] - 2026-04-30
 
 ### Added

package/generate-spec/SKILL.md

@@ -29,8 +29,7 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 
 - Confirm the target workspace root, feature name, and a kebab-case `change_name`.
 - Review only the code, configuration, and external docs needed to understand the requested behavior.
-- If the change depends on frameworks, libraries, SDKs, APIs, CLIs, hosted services, or other external systems, find and read the relevant official documentation before drafting requirements.
-- Treat official documentation lookup as mandatory evidence gathering, not an optional refinement step.
+- **Official documentation lookup is mandatory** when the change depends on frameworks, libraries, SDKs, APIs, CLIs, hosted services, or other external systems. This is a required evidence-gathering step, not an optional refinement.
 - Use the official docs to verify expected behavior, supported constraints, configuration surface, integration contracts, and any implementation limits that should shape the spec.
 - Record the references that should appear in `spec.md` and the dependency evidence that should appear in `contract.md`.
 - Inspect existing `docs/plans/` directories before deciding whether to edit an existing plan set.
@@ -147,16 +146,15 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 
 ### 7) Fill `checklist.md`
 
-- Use checkbox format `- [ ]` for checklist items, except structured placeholder fields that are intentionally left for later fill-in.
-- Treat the template as a starting point and adapt it to the actual scope.
-- Remove or rewrite template examples that are not part of the real plan instead of leaving them as fake work to be checked later.
-- Map observable behaviors to requirement IDs and real test case IDs.
-- Use `$test-case-strategy` to choose the smallest test level that proves each risk and to define meaningful oracles before implementation.
-- Record risk class, oracle/assertion focus, dependency strategy, and test results.
-- Property-based coverage is required for business-logic changes unless a concrete `N/A` reason is recorded.
-- For decision sections, create as many records as needed for distinct flows or risk slices; do not collapse unrelated decisions into one record.
-- Within each decision record, keep only the selected strategy or clearly mark the non-selected path as `N/A`; never treat mutually exclusive choices inside one record as multiple completed outcomes.
-- For completion-summary sections, create as many completion records as needed for distinct flows, requirement groups, or workstreams; do not force the whole spec into a single completion line when different parts finish differently.
+- Use checkbox format `- [ ]` for checklist items.
+- Adapt the template to actual scope; remove inapplicable items.
+- Map observable behaviors to requirement IDs and test case IDs using `$test-case-strategy`.
+- Each Behavior-to-Test item: `[CL-xx]: [behavior] — R?.? → [Test IDs] — Result: [status]`.
+- Property-based coverage required for business-logic changes unless `N/A` with concrete reason.
+- Hardening items: keep as single-line checkboxes with `N/A` + reason when not applicable.
+- E2E/Integration decisions: one checkbox per decision with inline reason.
+- Execution summary: one checkbox per test category with status.
+- Completion records: one checkbox per flow/group with status and remaining items.
 
 ### 8) Process clarifications and approval
 

package/generate-spec/references/templates/checklist.md

@@ -4,104 +4,49 @@
 - Feature: [Feature Name]
 
 ## Usage Notes
-- This checklist is a starter template. Add, remove, or rewrite items based on actual scope.
-- Use `- [ ]` for all items; mark completed items as `- [x]`.
-- The final completion summary section may use structured placeholders instead of checkboxes.
-- If an item is not applicable, keep `N/A` with a concrete reason.
-- Do not mark placeholder examples or mutually exclusive alternatives as completed unless they were actually selected and executed.
-- Duplicate or remove decision-record blocks as needed; the final document should contain as many records as the real change requires.
-- Duplicate or remove completion-record blocks as needed; the final document should contain as many records as the real change requires.
-- Suggested test result values: `PASS / FAIL / BLOCKED / NOT RUN / N/A`.
-- Use `$test-case-strategy` to choose test levels, define meaningful oracles, and record unit drift checks for atomic tasks.
-- For business-logic changes, property-based coverage is required unless a concrete `N/A` reason is recorded.
-- Each checklist item should map to a distinct risk; avoid repeating shallow happy-path cases.
 
-## Clarification & Approval Gate (required when clarification replies exist)
-- [ ] User clarification responses are recorded (map to `spec.md`; if none, mark `N/A`).
-- [ ] Affected plans are reviewed/updated (`spec.md` / `tasks.md` / `checklist.md` / `contract.md` / `design.md`; if no updates needed, mark `N/A` + reason).
-- [ ] Explicit user approval on updated specs is obtained (date/conversation reference: [to be filled]).
+- Add/remove items based on actual scope; keep only applicable items.
+- Use `$test-case-strategy` for test level selection, oracle design, and drift-check planning.
+- Property-based coverage required for business-logic changes unless `N/A` with reason.
+- Test result values: `PASS / FAIL / BLOCKED / NOT RUN / N/A`.
 
-## Behavior-to-Test Checklist (customizable)
+## Clarification & Approval Gate
 
-- [ ] CL-01 [Observable behavior]
-  - Requirement mapping: [R1.x]
-  - Actual test case IDs: [UT/PBT/IT/E2E-xx]
-  - Test level: [Unit / Property-based / Integration / E2E]
-  - Risk class: [boundary / authorization / concurrency / external failure / data integrity / adversarial abuse / regression]
-  - Property/matrix focus: [invariant / generated business input space / external state matrix / adversarial case]
-  - External dependency strategy: [none / mocked service states / near-real dependency]
-  - Oracle/assertion focus: [exact output / persisted state / side effects / no partial write / compensation / emitted event / permission denial]
-  - Unit drift check: [UT-xx target unit; expected result/assertion, or N/A with reason]
-  - Test result: `PASS / FAIL / BLOCKED / NOT RUN / N/A`
-  - Notes (optional): [risk, limitation, observation]
+- [ ] Clarification responses recorded (or `N/A` if none).
+- [ ] Affected plans updated after clarification (or `N/A` + reason).
+- [ ] Explicit approval obtained (date/ref: [to be filled]).
 
-- [ ] CL-02 [Observable behavior]
-  - Requirement mapping: [R?.?]
-  - Actual test case IDs: [UT/PBT/IT/E2E-xx]
-  - Test level: [Unit / Property-based / Integration / E2E]
-  - Risk class: [boundary / authorization / concurrency / external failure / data integrity / adversarial abuse / regression]
-  - Property/matrix focus: [invariant / generated business input space / external state matrix / adversarial case]
-  - External dependency strategy: [none / mocked service states / near-real dependency]
-  - Oracle/assertion focus: [exact output / persisted state / side effects / no partial write / compensation / emitted event / permission denial]
-  - Unit drift check: [UT-xx target unit; expected result/assertion, or N/A with reason]
-  - Test result: `PASS / FAIL / BLOCKED / NOT RUN / N/A`
-  - Notes (optional): [risk, limitation, observation]
+## Behavior-to-Test Checklist
 
-- [ ] CL-03 [Observable behavior]
-  - Requirement mapping: [R?.?]
-  - Actual test case IDs: [UT/PBT/IT/E2E-xx]
-  - Test level: [Unit / Property-based / Integration / E2E]
-  - Risk class: [boundary / authorization / concurrency / external failure / data integrity / adversarial abuse / regression]
-  - Property/matrix focus: [invariant / generated business input space / external state matrix / adversarial case]
-  - External dependency strategy: [none / mocked service states / near-real dependency]
-  - Oracle/assertion focus: [exact output / persisted state / side effects / no partial write / compensation / emitted event / permission denial]
-  - Unit drift check: [UT-xx target unit; expected result/assertion, or N/A with reason]
-  - Test result: `PASS / FAIL / BLOCKED / NOT RUN / N/A`
-  - Notes (optional): [risk, limitation, observation]
+- [ ] CL-01: [Observable behavior] — R?.? → [Test IDs] — Result: `[status]`
+- [ ] CL-02: [Observable behavior] — R?.? → [Test IDs] — Result: `[status]`
+- [ ] CL-03: [Observable behavior] — R?.? → [Test IDs] — Result: `[status]`
 
-## Required Hardening Records
-- [ ] Regression tests are added/updated for bug-prone or high-risk behavior, or `N/A` is recorded with a concrete reason.
-- [ ] Focused unit drift checks are defined for non-trivial atomic implementation tasks, or `N/A` is recorded with the replacement verification and concrete reason.
-- [ ] Property-based coverage is added/updated for changed business logic, or `N/A` is recorded with a concrete reason.
-- [ ] External services in the business logic chain are mocked/faked for scenario testing, or `N/A` is recorded with a concrete reason.
-- [ ] Adversarial/penetration-style cases are added/updated for abuse paths and edge combinations, or `N/A` is recorded with a concrete reason.
-- [ ] Authorization, invalid transition, replay/idempotency, and concurrency risks are evaluated; uncovered items are marked `N/A` with concrete reasons.
-- [ ] Assertions verify business outcomes and side effects/no-side-effects, not only "returns 200" or "does not throw".
-- [ ] Test fixtures are reproducible (fixed seed/clock/fixtures) or `N/A` is recorded with a concrete reason.
+## Hardening Checklist
 
-## E2E / Integration Decision Records
+- [ ] Regression tests for bug-prone/high-risk behavior (or `N/A` + reason).
+- [ ] Unit drift checks for non-trivial tasks (or `N/A` + reason).
+- [ ] Property-based coverage for business logic (or `N/A` + reason).
+- [ ] External services mocked/faked (or `N/A` + reason).
+- [ ] Adversarial cases for abuse paths (or `N/A` + reason).
+- [ ] Authorization, idempotency, concurrency risks evaluated (or `N/A` + reason).
+- [ ] Assertions verify outcomes/side-effects, not just "returns 200".
+- [ ] Fixtures reproducible (fixed seed/clock) (or `N/A` + reason).
 
-### Decision Record 1: [Flow / Requirement / Risk Slice]
-- Requirement mapping: [R?.? / CL-xx]
-- Decision: [Build E2E / Cover with integration instead / Existing coverage already sufficient / N/A]
-- Linked case IDs: [E2E-xx / IT-xx / existing suite reference]
-- Reason: [importance, cross-layer risk, stability/cost tradeoff, or why no extra coverage is needed]
+## E2E / Integration Decisions
 
-### Decision Record 2: [Flow / Requirement / Risk Slice]
-- Requirement mapping: [R?.? / CL-xx]
-- Decision: [Build E2E / Cover with integration instead / Existing coverage already sufficient / N/A]
-- Linked case IDs: [E2E-xx / IT-xx / existing suite reference]
-- Reason: [importance, cross-layer risk, stability/cost tradeoff, or why no extra coverage is needed]
+- [ ] [Flow/Risk]: [E2E / Integration replacement / Existing coverage / N/A] — Reason: [why]
 
-## Execution Summary (fill with actual results)
-- [ ] Unit tests: `PASS / FAIL / NOT RUN / N/A`
-- [ ] Regression tests: `PASS / FAIL / NOT RUN / N/A`
-- [ ] Property-based tests: `PASS / FAIL / NOT RUN / N/A`
-- [ ] Integration tests: `PASS / FAIL / NOT RUN / N/A`
-- [ ] E2E tests: `PASS / FAIL / NOT RUN / N/A`
-- [ ] External service mock scenarios: `PASS / FAIL / NOT RUN / N/A`
-- [ ] Adversarial/penetration-style cases: `PASS / FAIL / NOT RUN / N/A`
+## Execution Summary
 
-## Completion Records
+- [ ] Unit: `[status]`
+- [ ] Regression: `[status]`
+- [ ] Property-based: `[status]`
+- [ ] Integration: `[status]`
+- [ ] E2E: `[status]`
+- [ ] Mock scenarios: `[status]`
+- [ ] Adversarial: `[status]`
 
-### Completion Record 1: [Flow / Requirement Group / Workstream]
-- Requirement mapping: [R?.? / Task N / CL-xx]
-- Completion status: [completed / partially completed / blocked / deferred]
-- Remaining applicable items: [None / list remaining items]
-- Notes: [brief execution-backed summary]
+## Completion Records
 
-### Completion Record 2: [Flow / Requirement Group / Workstream]
-- Requirement mapping: [R?.? / Task N / CL-xx]
-- Completion status: [completed / partially completed / blocked / deferred]
-- Remaining applicable items: [None / list remaining items]
-- Notes: [brief execution-backed summary]
+- [ ] [Flow/Group]: [completed / partial / blocked / deferred] — Remaining: [None / list]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "3.8.3",
+  "version": "3.8.4",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",