@laitszkin/apollo-toolkit 3.3.2 → 3.3.4

package/CHANGELOG.md

@@ -7,6 +7,16 @@ All notable changes to this repository are documented in this file.
 ### Added
 - (None yet)
 
+## [v3.3.4] - 2026-04-27
+
+### Changed
+- Tighten `implement-specs-with-worktree` so the skill must verify it is operating inside the intended isolated worktree before any edits, and never mutate product files from the parent checkout.
+
+## [v3.3.3] - 2026-04-27
+
+### Changed
+- Require `review-change-set` after merge verification before `merge-changes-from-local-branches` can continue into archival or submission.
+
 ## [v3.3.2] - 2026-04-27
 
 ### Changed

package/implement-specs-with-worktree/SKILL.md

@@ -4,12 +4,13 @@ description: >-
   Read a specs planning set (spec.md, tasks.md, checklist.md, contract.md, design.md)
   from `docs/plans/{YYYY-MM-DD}/{change_name}/` or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/`
   plus parent `coordination.md` when present, and implement the approved tasks
-  within an isolated git worktree. Use when the user asks to implement from an
-  existing spec set, execute a spec plan, or work on a feature branch without
-  affecting the parent working tree. If not already in a worktree, create a new
-  worktree with a spec-named branch from the same parent branch as the worktree
-  base, implement all planned tasks, then commit the changes to that local
-  branch when complete.
+  within an isolated git worktree, with every code, test, and spec edit made
+  inside that worktree rather than the parent checkout. Use when the user asks
+  to implement from an existing spec set, execute a spec plan, or work on a
+  feature branch without affecting the parent working tree. If not already in a
+  worktree, create a new worktree with a spec-named branch from the same parent
+  branch as the worktree base, implement all planned tasks, then commit the
+  changes to that local branch when complete.
 ---
 
 # Implement Specs with Worktree
@@ -24,7 +25,7 @@ description: >-
 ## Standards
 
 - Evidence: Read and understand the complete specs set before starting implementation, identify the authoritative parent branch that the worktree should inherit from, verify whether the requested scope is already implemented on that parent branch or current main working tree, and when the requested plan path is missing from the current worktree verify where the authoritative copy actually lives before substituting any nearby spec.
-- Execution: Create or use an isolated worktree for implementation only when the requested spec still needs work, sync the exact approved plan set into that worktree when it is missing there, create the worktree branch from the same parent branch as the worktree base, use the spec-set name as the canonical branch/worktree name, prefer direct `git` ref checks over brittle shell inference when deciding whether a branch or worktree already exists, and commit to a local branch when done.
+- Execution: Create or use an isolated worktree for implementation only when the requested spec still needs work, sync the exact approved plan set into that worktree when it is missing there, create the worktree branch from the same parent branch as the worktree base, use the spec-set name as the canonical branch/worktree name, prefer direct `git` ref checks over brittle shell inference when deciding whether a branch or worktree already exists, and commit to a local branch when done. Do not edit product files from the parent checkout; every implementation, test, and spec backfill change must happen inside the active worktree directory after verifying `git rev-parse --show-toplevel` and `pwd` point at the same worktree root.
 - Quality: Complete all planned tasks, run relevant tests, backfill the spec documents with actual completion status, avoid dragging unrelated sibling specs into the worktree just because they share a batch directory, revert unrelated formatter-only noise outside the spec-owned scope before committing, if branch/worktree creation reports ambiguous state re-check the actual git refs and worktree list before retrying, and when using targeted Rust `cargo test` selectors remember Cargo accepts only one positional test filter so each distinct selector needs its own confirmed command.
 - Output: Keep the worktree branch clean with only the intended implementation commits.
 
@@ -59,6 +60,7 @@ Implement approved spec planning sets in an isolated git worktree, ensuring the
 - Run `git worktree list` to see existing worktrees and branches.
 - Determine if the current session is already inside a worktree (check `git rev-parse --show-toplevel` and compare with `git worktree list`).
 - If the current worktree is missing the exact requested plan set, sync that plan into the worktree before coding and re-read the synced files there so implementation happens against the same plan snapshot that will be backfilled later.
+- Before making any edits, confirm the active shell is inside the intended worktree directory; if not, stop editing, create or enter the required worktree first, and only then continue.
 - Determine the authoritative parent branch for the new worktree:
   - if the current checkout already comes from a branch, reuse that branch as the base
   - if the current session is inside a detached worktree, identify the parent branch that owns that worktree before creating another branch from it
@@ -85,6 +87,7 @@ If not already in a worktree, or if the user explicitly requests a fresh worktre
   git worktree add ../<spec-name> <branch-name>
   ```
 - Move into the new worktree directory and begin work there.
+- Do not start editing until the shell is operating inside the new worktree directory and the worktree root has been verified.
 - When checking whether the target branch or worktree already exists, use direct git evidence instead of shell heuristics:
   ```bash
   git show-ref --verify --quiet refs/heads/<branch-name>
@@ -144,6 +147,7 @@ After implementation and testing:
 ## Working Rules
 
 - Always work in an isolated worktree to keep the parent checkout clean.
+- Treat the parent checkout as read-only for implementation work; use it only for inspection, worktree creation, or verification, never for file edits.
 - Treat an already-landed spec as complete work, not as a reason to recreate a duplicate worktree.
 - Keep the new branch based on the same parent branch as the worktree base; do not silently rebase the workflow onto a different branch.
 - Use the spec-set name as the canonical identifier for the branch and worktree unless the user explicitly asks for a different naming scheme.

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

@@ -4,20 +4,22 @@ description: >-
   Read changes from local branches identified by branch name and merge them back
   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). Run `archive-specs`
-  after merge verification 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.
+  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.
 ---
 
 # Merge Changes from Local Branches
 
 ## Dependencies
 
-- 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.
+- 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.
 - Conditional: none.
 - Optional: none.
 - Fallback: If git operations fail, stop and report the error.
@@ -25,7 +27,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, delete each successfully merged source branch and its detached worktree only after the merged result is confirmed, run `archive-specs` 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, 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.
 - 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.
 
@@ -116,9 +118,16 @@ 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 and the current-branch state has been verified, invoke `archive-specs`.
+- 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`.
 - 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.
@@ -141,7 +150,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 plus archival/doc synchronization pass, invoke `commit-and-push` for the original current branch so the final submission flow owns:
+- 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:
   - `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.3.2",
+  "version": "3.3.4",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",