@laitszkin/apollo-toolkit 3.5.0 → 3.6.0

package/AGENTS.md

@@ -52,6 +52,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can record multi-account spending and balance changes in monthly Excel ledgers with summary analytics and charts.
 - Users can recover missing or archived `docs/plans/...` spec sets from issue context, git history, and repository evidence before continuing feature work.
 - Users can review the current git change set from an unbiased reviewer perspective to find abstraction opportunities and simplification candidates.
+- Users can review recent or user-specified spec-backed changes against the governing planning documents, treating unmet business goals as the most severe findings before secondary edge-case, security, and code-review checks.
 - Users can process GitHub pull request review comments and resolve addressed threads.
 - Users can perform repository-wide code reviews and publish confirmed findings as GitHub issues.
 - Users can schedule a bounded project runtime window, stop it automatically, and analyze module health from captured logs.

package/CHANGELOG.md

@@ -7,6 +7,14 @@ All notable changes to this repository are documented in this file.
 ### Added
 - (None yet)
 
+## [v3.6.0] - 2026-04-28
+
+### Added
+- Add `review-spec-related-changes`, a spec-compliance review skill that checks recent or named planning documents against implementation evidence and treats unmet business goals as the most severe findings before secondary edge-case, security, and code-review checks.
+
+### Changed
+- Remove the post-merge code-review gate from `merge-changes-from-local-branches` so spec-related review now lives in the dedicated `review-spec-related-changes` skill.
+
 ## [v3.5.0] - 2026-04-28
 
 ### Added

package/README.md

@@ -45,6 +45,7 @@ A curated skill catalog for Codex, OpenClaw, Trae, Agents, and Claude Code with
 - resolve-review-comments
 - review-change-set
 - review-codebases
+- review-spec-related-changes
 - scheduled-runtime-health-check
 - shadow-api-model-research
 - solana-development
@@ -202,6 +203,7 @@ Compatibility note:
 - `recover-missing-plan` is a local skill used by `enhance-existing-features` and `ship-github-issue-fix` when a referenced `docs/plans/...` spec set is missing or archived.
 - `maintain-skill-catalog` can conditionally use `find-skills`, but its install source is not verified in this repository, so it is intentionally omitted from the table.
 - `read-github-issue` uses GitHub CLI (`gh`) directly for remote issue discovery and inspection, so it does not add any extra skill dependency.
+- `review-spec-related-changes` is a local skill that depends on `review-change-set`, `discover-edge-cases`, and `harden-app-security` for secondary code-practice checks after business-goal completion is reviewed against the governing specs.
 
 ## Release publishing
 

package/merge-changes-from-local-branches/SKILL.md

@@ -5,21 +5,18 @@ description: >-
   into the current local branch. When conflicts arise, auto-resolve them by
   keeping correct functionality (preferring the more recent change on the same
   line, or the change that preserves working behavior). After merge verification,
-  require `review-change-set` to review the merged code and confirm it still
-  matches the active spec documents before any submission workflow continues.
-  Run `archive-specs` only after that review gate passes so completed plan sets
-  are archived and durable project docs are synchronized, then hand the current
-  branch state to `commit-and-push` so the final submit workflow commits and
-  pushes on that same local branch. Use when the user asks to consolidate local
-  branch work, merge named branches into the current branch, or prepare the
-  current branch for integration.
+  run `archive-specs` so completed plan sets are archived and durable project
+  docs are synchronized, then hand the current branch state to `commit-and-push`
+  so the final submit workflow commits and pushes on that same local branch.
+  Use when the user asks to consolidate local branch work, merge named branches
+  into the current branch, or prepare the current branch for integration.
 ---
 
 # Merge Changes from Local Branches
 
 ## Dependencies
 
-- Required: `review-change-set` to review the merged code and confirm spec alignment before submission, `archive-specs` to archive completed plan sets and synchronize durable project docs after the review gate passes, and `commit-and-push` for the final current-branch submission flow.
+- Required: `archive-specs` to archive completed plan sets and synchronize durable project docs after merge verification, and `commit-and-push` for the final current-branch submission flow.
 - Conditional: none.
 - Optional: none.
 - Fallback: If git operations fail, stop and report the error.
@@ -27,7 +24,7 @@ description: >-
 ## Standards
 
 - Evidence: Inspect the original current branch, local branches, branch-name matches provided by the user or active spec names, actual conflicting files, and any active batch-spec `coordination.md` merge-order guidance before deciding what to merge.
-- Execution: Merge only the relevant named branches back into the original current branch, read any active batch-spec `coordination.md` and honor its documented merge order when present, resolve conflicts by reading both sides and editing the merged result to preserve shipped behavior, verify the merged state, run `review-change-set` to confirm the merged code still matches the active spec documents, delete each successfully merged source branch and its detached worktree only after the merged result is confirmed, run `archive-specs` only after the review gate passes so completed plan sets are archived and durable docs are synchronized, then hand the final current-branch state to `commit-and-push` so changelog/readiness/commit/push work happens through the shared submission workflow on the same branch.
+- Execution: Merge only the relevant named branches back into the original current branch, read any active batch-spec `coordination.md` and honor its documented merge order when present, resolve conflicts by reading both sides and editing the merged result to preserve shipped behavior, verify the merged state, delete each successfully merged source branch and its detached worktree only after the merged result is confirmed, run `archive-specs` after merge verification so completed plan sets are archived and durable docs are synchronized, then hand the final current-branch state to `commit-and-push` so changelog/readiness/commit/push work happens through the shared submission workflow on the same branch.
 - Quality: Never use blanket timestamp rules or default `-X ours/theirs` conflict resolution as the primary merge strategy, never infer in-scope branches from ancestry heuristics when branch names already define the target set, and do not declare success until the final current-branch state has been checked, verified, and cleared for post-merge archival/doc-sync work.
 - Output: Produce a clean current branch with all relevant named-branch changes integrated and ready for the shared submit workflow.
 
@@ -118,16 +115,9 @@ For each in-scope named branch:
   ```
 - If verification fails, fix the merged state on the current branch before proceeding.
 
-### 4.5) Review the merged change set before submission
-
-- After merge verification passes, invoke `review-change-set` on the merged current branch.
-- Compare the merged code against the active spec documents and any relevant `docs/plans/` artifacts that governed the merge.
-- Do not proceed to archival or submission until the review returns no actionable findings and the merged state is confirmed to match the spec documents.
-- If review finds a problem or spec mismatch, fix the current branch, rerun verification, and review again before continuing.
-
 ### 5) Archive completed specs and sync durable project docs
 
-- After all in-scope merges succeed, the current-branch state has been verified, and `review-change-set` has confirmed the merged code matches the spec documents, invoke `archive-specs`.
+- After all in-scope merges succeed and the current-branch state has been verified, invoke `archive-specs`.
 - Let `archive-specs` convert and archive any completed `docs/plans/...` spec sets that now reflect the delivered outcome.
 - Let `archive-specs` synchronize durable project docs and `AGENTS.md` when the merged result changed operator workflows, repository guidance, or user-visible behavior.
 - Do not proceed to the final submission commit while required archival or documentation updates remain unfinished.
@@ -150,7 +140,7 @@ For each in-scope named branch:
   - the currently checked-out branch
   - branches that were skipped, failed to merge, or still need manual follow-up
 - If `git branch -d` refuses deletion because the branch is not actually merged, stop and report the branch instead of forcing deletion with `-D`.
-- Once merge verification, `review-change-set`, and archival/doc synchronization pass, invoke `commit-and-push` for the original current branch so the final submission flow owns:
+- Once merge verification and archival/doc synchronization pass, invoke `commit-and-push` for the original current branch so the final submission flow owns:
   - `CHANGELOG.md` readiness
   - the final commit creation on the original current branch
   - the user-requested push on that same branch

package/package.json

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

package/review-spec-related-changes/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LaiTszKin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,53 @@
+# review-spec-related-changes
+
+`review-spec-related-changes` reviews implementation changes against recent or user-specified planning documents.
+
+## What this skill does
+
+This skill:
+
+1. Resolves the governing `docs/plans/...` spec scope from user input or recent repository changes.
+2. Checks whether each business goal and acceptance criterion is actually implemented.
+3. Treats unmet business goals as the most severe review findings.
+4. Runs secondary code-practice review through `review-change-set`, `discover-edge-cases`, and `harden-app-security` for code-affecting scopes.
+5. Reports business-goal gaps separately from edge-case, security, and maintainability findings.
+
+## When to use
+
+Use this skill when the task asks you to:
+
+- review whether recent spec-backed implementation work is complete,
+- compare current changes against a named spec directory,
+- check whether delivered code satisfies `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, or `design.md`,
+- perform a final spec-compliance review before archive, submission, PR, or release work.
+
+## Core principles
+
+- Business-goal completion is reviewed first.
+- Missing required behavior is more severe than ordinary code-practice issues.
+- Secondary edge-case, security, and code-review findings remain clearly separated.
+- Findings must cite concrete spec and code evidence.
+
+## Example
+
+Prompt example:
+
+```text
+Use $review-spec-related-changes to review the changes related to docs/plans/2026-04-28/order-routing.
+List any business goals that were not fully achieved, then run edge-case, security, and code-review checks on the related code.
+```
+
+Expected behavior:
+
+- the named spec set is read before judging the code,
+- business-goal gaps are listed first and treated as highest severity,
+- secondary review skills are invoked for the same implementation scope,
+- the final report separates spec-compliance findings from edge-case, security, and code-review findings.
+
+## References
+
+- [`SKILL.md`](./SKILL.md) - full workflow and execution rules.
+
+## License
+
+MIT

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

@@ -0,0 +1,110 @@
+---
+name: review-spec-related-changes
+description: Review recent or user-specified spec-related changes against the governing `docs/plans/...` spec documents, treat unmet business goals as the most severe findings, and then run code-practice cross-checks through `review-change-set`, `discover-edge-cases`, and `harden-app-security`. Use when users ask whether implemented work actually satisfies a spec, wants a spec compliance review, or asks to review changes related to recent or named planning documents.
+---
+
+# Review Spec Related Changes
+
+## Dependencies
+
+- Required: `review-change-set`, `discover-edge-cases`, and `harden-app-security` for code-affecting spec-related changes.
+- Conditional: none.
+- Optional: none.
+- Fallback: If any required review dependency is unavailable for a code-affecting scope, stop and report the missing dependency instead of returning a partial pass.
+
+## Standards
+
+- Evidence: Read the governing spec documents, the related git changes, and the minimum implementation context before deciding whether the business goal was met.
+- Execution: Resolve the spec scope first, review business-goal completion before any secondary code-practice review, then run the required review skills on the same implementation scope.
+- Quality: Treat unmet or partially met business goals as the highest-severity findings, keep secondary edge-case/security/code-review findings outside the business-goal verdict, and avoid speculative issues that are not backed by code or spec evidence.
+- Output: Return a prioritized issue list with business-goal gaps first, followed by edge-case, security, and code-review findings, each tied to specific spec and code evidence.
+
+## Goal
+
+Determine whether the implementation actually satisfies the relevant planning documents, then separately assess whether the related code is safe, robust, and maintainable.
+
+## Scope Resolution
+
+### User-specified spec documents
+
+- If the user names a spec directory or file, read every governing document in that spec set, including `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, and batch-level `coordination.md` when present.
+- Treat the named spec documents as the authoritative business goal unless the repository contains a newer superseding plan that the user explicitly referenced.
+- Map the spec to implementation changes using task entries, owned files, git diff paths, branch names, commit messages, and code references from the spec.
+
+### Recent spec-related changes
+
+- If the user asks for recent spec-related review without naming a spec, inspect the current git state first:
+  ```bash
+  git status -sb
+  git diff --name-only
+  git diff --cached --name-only
+  ```
+- Look for changed or recently touched planning documents under `docs/plans/`, `docs/archive/plans/`, or the repository's documented planning location.
+- If no planning document changed, inspect recent commits and active plan directories to identify the most recent spec set that plausibly governs the current implementation.
+- If multiple candidate spec sets remain plausible and cannot be separated by changed files or branch names, stop and report the ambiguity instead of guessing.
+
+## Workflow
+
+### 1) Build the spec baseline
+
+- Read the governing spec documents end-to-end.
+- Extract the concrete business goals, acceptance criteria, non-goals, deferred work, and explicit verification requirements.
+- Build a compact checklist of claims that can be proven or disproven from code, tests, docs, or command output.
+- Keep business goals separate from implementation-quality expectations. A clean implementation does not compensate for an unmet business requirement.
+
+### 2) Map implementation evidence
+
+- Read the related diff, staged changes, commits, or changed files that correspond to the spec scope.
+- Follow the minimum dependency chain needed to understand whether the behavior is actually implemented.
+- Run or inspect the verification commands named by the spec when they are available and safe to run.
+- Mark each business goal as:
+  - `Met`: direct implementation and verification evidence exists.
+  - `Partially met`: some required behavior exists, but an acceptance criterion, integration path, or verification proof is missing.
+  - `Not met`: implementation evidence is absent or contradicts the spec.
+  - `Deferred/N/A`: the spec explicitly excludes or defers the item.
+
+### 3) Review business-goal completion first
+
+- Report every `Not met` and `Partially met` business goal before secondary review findings.
+- Assign the highest severity to business-goal failures because they mean the delivered change does not satisfy the requested work.
+- Include exact spec evidence and code evidence for each gap.
+- Do not continue into archival, submission, or release recommendations while business-goal failures remain unresolved.
+
+### 4) Run secondary code-practice reviews
+
+After the business-goal pass is complete, invoke the required review skills on the same code-affecting scope:
+
+- Use `review-change-set` to identify architecture, abstraction, and simplification findings in the related diff.
+- Use `discover-edge-cases` to identify reproducible boundary, failure-path, state, and observability risks.
+- Use `harden-app-security` to identify reproducible vulnerabilities and adversarial trust-boundary failures.
+
+Keep these findings separate from the business-goal verdict unless the issue also prevents a required acceptance criterion from being satisfied.
+
+### 5) Produce the final review
+
+Return findings in this order:
+
+1. Business-goal failures
+   - Severity: always highest for unmet or partially met required goals.
+   - Include spec evidence, implementation evidence, and the missing acceptance criterion.
+2. Edge-case findings
+   - Include reproduction or concrete trigger evidence.
+3. Security findings
+   - Include exploit path, protected asset, and reproducibility evidence.
+4. Code-review findings
+   - Include architecture, abstraction, simplification, or maintainability evidence.
+5. Passing evidence
+   - Summarize the business goals that were confirmed met.
+6. Residual uncertainty
+   - List unverified checks, commands not run, ambiguous spec mappings, or external dependencies that could not be proven.
+
+If no actionable issue is found, state that no business-goal, edge-case, security, or code-review findings were identified, and still list the spec documents and verification evidence reviewed.
+
+## Working Rules
+
+- Do not edit code, tests, or specs during this review.
+- Do not archive specs, commit, push, tag, or release from this skill.
+- Do not let secondary code quality findings bury business-goal failures.
+- Do not treat checked tasks as proof by themselves; verify the implementation.
+- Do not infer success from author intent, branch names, or prior conversation context unless the repository evidence supports it.
+- Prefer fewer confirmed findings over broad speculative feedback.

package/review-spec-related-changes/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Review Spec Related Changes"
+  short_description: "Review spec-backed changes for business-goal completion and secondary code-practice risks"
+  default_prompt: "Use $review-spec-related-changes to resolve the recent or user-specified spec documents, verify each business goal and acceptance criterion against the related implementation evidence, treat unmet business goals as the most severe findings, and then run $review-change-set, $discover-edge-cases, and $harden-app-security on the same code-affecting scope for secondary code-practice review."