@laitszkin/apollo-toolkit 2.14.10 → 2.14.12

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.14.12] - 2026-04-10
+
+### Changed
+- Tighten `implement-specs-with-worktree` so detached or temporary worktrees must recover the exact requested `docs/plans/...` spec set from the authoritative branch or main working tree before coding, instead of substituting nearby plans.
+- Require `implement-specs-with-worktree` to sync only the in-scope spec directory plus its governing batch `coordination.md`, avoiding accidental sibling-spec imports into the worktree.
+
+## [v2.14.11] - 2026-04-09
+
+### Changed
+- Re-scope `merge-changes-from-local-branches` so it merges only verified child branches that forked from the current branch, and lands the result back onto that same current branch instead of sweeping all local branches into `main`.
+- Require `merge-changes-from-local-branches` to run `archive-specs` after merge verification so completed plan sets are archived and durable project docs are synchronized before `commit-and-push` creates the final current-branch submission.
+
 ## [v2.14.10] - 2026-04-09
 
 ### Changed

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

@@ -22,9 +22,9 @@ description: >-
 
 ## Standards
 
-- Evidence: Read and understand the complete specs set before starting implementation.
-- Execution: Create or use an isolated worktree for implementation, follow the implementation standards from the dependent skills, and commit to a local branch when done.
-- Quality: Complete all planned tasks, run relevant tests, and backfill the spec documents with actual completion status.
+- Evidence: Read and understand the complete specs set before starting implementation, 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, sync the exact approved plan set into that worktree when it is missing there, follow the implementation standards from the dependent skills, and commit to a local branch when done.
+- Quality: Complete all planned tasks, run relevant tests, backfill the spec documents with actual completion status, and avoid dragging unrelated sibling specs into the worktree just because they share a batch directory.
 - Output: Keep the worktree branch clean with only the intended implementation commits.
 
 ## Goal
@@ -38,6 +38,11 @@ Implement approved spec planning sets in an isolated git worktree, ensuring main
 - Locate the specs directory. The path format is `docs/plans/{YYYY-MM-DD}/{change_name}/` for single-spec work, or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` for coordinated multi-spec work.
 - If the user provides a specific path, use that directly.
 - If only a `change_name` or date is given, search for matching directories under `docs/plans/`.
+- If the requested path is absent from the current worktree, stop and identify the authoritative source before implementing:
+  - inspect the main working tree and any relevant local branches/worktrees for that exact `docs/plans/...` path
+  - prefer the exact matching plan directory from the repository's authoritative branch or main working tree over archived, approximate, or sibling plan directories
+  - if the plan lives under a batch directory, sync only the requested spec directory plus the shared `coordination.md` that governs it
+  - do not copy neighboring sibling spec directories into the worktree unless the user explicitly expanded scope
 - When the plan sits under a batch directory, also read the sibling `coordination.md` before implementation.
 - Read all five spec files:
   - `spec.md` — requirements and BDD behaviors
@@ -52,6 +57,7 @@ Implement approved spec planning sets in an isolated git worktree, ensuring main
 
 - 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.
 
 ### 3) Create a new worktree if needed
 

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

@@ -1,76 +1,84 @@
 ---
 name: merge-changes-from-local-branches
 description: >-
-  Read changes from all local git branches and merge them into the local main
-  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). Hand the final merged local branch state to `commit-and-push`
-  so the commit workflow can handle changelog/readiness steps and any required
-  spec archival before the work is considered complete. Use when the user asks
-  to consolidate local branch work, merge all changes into main, or prepare local
-  branches for integration.
+  Read changes from local child branches that forked from the current local
+  branch and merge them back into that same 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 child-branch work,
+  merge branches branched from the current branch, or prepare the current branch
+  for integration.
 ---
 
 # Merge Changes from Local Branches
 
 ## Dependencies
 
-- Required: `commit-and-push` for the final local-branch submission flow after merge verification.
+- 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.
 
 ## Standards
 
-- Evidence: Inspect the current branch state, local branches, ahead/behind status, actual conflicting files, and any active batch-spec `coordination.md` merge-order guidance before deciding what to merge.
-- Execution: Merge only the relevant local branches into `main` sequentially, 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 branch and its detached worktree only after the merged result is confirmed, then hand the final local branch state to `commit-and-push` so commit/changelog/spec-archival work happens through the shared submission workflow.
-- Quality: Never use blanket timestamp rules or default `-X ours/theirs` conflict resolution as the primary merge strategy, and do not declare success until the final `main` state has been checked and verified.
-- Output: Produce a clean local main branch with all local changes integrated and ready for the shared submit workflow.
+- Evidence: Inspect the original current branch, local branches, ahead/behind status, verified child-branch ancestry, actual conflicting files, and any active batch-spec `coordination.md` merge-order guidance before deciding what to merge.
+- Execution: Merge only the relevant child branches that verifiably forked from the original current branch back into that same 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 child 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.
+- Quality: Never use blanket timestamp rules or default `-X ours/theirs` conflict resolution as the primary merge strategy, never infer branch parentage without git evidence, 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 child-branch changes integrated and ready for the shared submit workflow.
 
 ## Goal
 
-Consolidate all local branch changes into the local main branch with automatic conflict resolution that preserves correct functionality.
+Consolidate verified child-branch changes back into the original current branch with automatic conflict resolution that preserves correct functionality.
 
 ## Workflow
 
-### 1) Inventory all local branches
+### 1) Inventory the current branch and in-scope child branches
 
 - Run `git branch` to list all local branches.
 - Check the current branch with `git branch --show-current` and capture `git status -sb`.
 - Inspect active planning artifacts under `docs/plans/` and look for batch roots that still contain live spec sets plus a `coordination.md`.
 - When an active batch is present, read its `coordination.md` before deciding merge order.
-- Compare each candidate branch against `main` with `git log --oneline main..branch`, `git diff --stat main...branch`, or equivalent evidence so empty or already-merged branches are skipped.
+- Treat the original current branch as the authoritative merge target for the whole workflow; do not silently switch that target to `main`.
+- Determine whether each candidate branch is a child branch of the current branch by using git evidence such as `git merge-base --fork-point <current-branch> <candidate>`, `git merge-base <current-branch> <candidate>`, and branch reflog/history when needed.
+- Accept a branch as in scope only when the evidence shows it actually forked from the current branch; skip parent branches, sibling branches, and unrelated local branches.
+- If child-branch ancestry is ambiguous, stop and report the ambiguity instead of guessing.
+- Compare each in-scope candidate branch against the current branch with `git log --oneline <current-branch>..<candidate>`, `git diff --stat <current-branch>...<candidate>`, or equivalent evidence so empty or already-merged branches are skipped.
 - For each branch, note:
   - Branch name
-  - Commits ahead of main
+  - Verified fork-point evidence from the current branch
+  - Commits ahead of the current branch
   - Last commit message (via `git log -1 --oneline`)
 
 ### 1.5) Resolve merge order from active batch specs
 
 - Treat active batch specs as authoritative merge-order guidance when they include a concrete `Merge order / landing order` entry in `coordination.md`.
 - Map branch names to the corresponding spec sets or worktrees using the batch folder names, spec-set names, and current git evidence; do not guess when the mapping is ambiguous.
-- Merge branches in the documented order when that order is explicit.
+- Merge only the in-scope child branches in the documented order when that order is explicit.
 - If multiple active batches exist, reconcile their merge-order guidance before merging; if the orders conflict or the branch-to-spec mapping is unclear, stop and report the ambiguity instead of choosing an arbitrary sequence.
 - If no active batch spec provides an explicit merge order, fall back to the normal branch inventory evidence and merge the relevant branches sequentially based on the safest verified order.
 
-### 2) Ensure clean state on main
+### 2) Ensure clean state on the original current branch
 
-- Check `git status` on `main`.
-- If `main` has uncommitted changes that are unrelated to the merge request, stop and report them instead of stashing automatically.
+- Check `git status` on the original current branch.
+- If the current branch has uncommitted changes that are unrelated to the merge request, stop and report them instead of stashing automatically.
+- Never change the authoritative target branch unless the user explicitly asks for a different destination.
 - Only proceed once you can state which branch or branches actually need to be merged.
 
 ### 3) Merge branches sequentially in the resolved order
 
-For each local branch (excluding main):
+For each in-scope child branch:
 
-1. Check out main:
+1. Check out the original current branch:
    ```bash
-   git checkout main
+   git checkout <current-branch>
    ```
 
 2. Merge the branch:
    ```bash
-   git merge <branch-name> --no-ff -m "Merge branch '<branch-name>' into main"
+   git merge <branch-name> --no-ff -m "Merge branch '<branch-name>' into <current-branch>"
    ```
 
 3. If conflicts occur, resolve them automatically using these rules:
@@ -94,7 +102,7 @@ For each local branch (excluding main):
 
 5. Complete the merge:
    ```bash
-   git commit -m "Merge branch '<branch-name>' into main"
+   git commit -m "Merge branch '<branch-name>' into <current-branch>"
    ```
 
 ### 4) Verify merged state
@@ -104,11 +112,19 @@ For each local branch (excluding main):
   ```bash
   npm test  # or yarn test, cargo test, etc.
   ```
-- If verification fails, fix the merged state on `main` before proceeding.
+- If verification fails, fix the merged state on the current branch before proceeding.
 
-### 5) Hand off the merged result for shared submission handling
+### 5) Archive completed specs and sync durable project docs
 
-- After a branch has been merged successfully and the merged `main` state has been verified, remove the source branch worktree if one exists:
+- 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.
+- If no completed spec sets or project-doc drift are present, record that evidence explicitly before moving on.
+
+### 6) Hand off the merged result for shared submission handling
+
+- After a child branch has been merged successfully and the merged current-branch state has been verified, remove the source branch worktree if one exists:
   ```bash
   git worktree list
   git worktree remove <worktree-path>
@@ -119,24 +135,25 @@ For each local branch (excluding main):
   ```
 - If a branch still has an attached worktree, remove the worktree before deleting the branch.
 - Never delete:
-  - `main`
+  - the original current 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 passes, invoke `commit-and-push` for the authoritative local branch so the final submission flow owns:
+- Once merge verification plus archival/doc synchronization pass, invoke `commit-and-push` for the original current branch so the final submission flow owns:
   - `CHANGELOG.md` readiness
-  - any required `archive-specs` run
-  - the final commit creation on the local target branch
-- Do not duplicate commit-message, changelog, or spec-archival logic inside this skill.
-- If a follow-up fix is required after verification, make that fix on `main` before handing off to `commit-and-push`.
+  - the final commit creation on the original current branch
+  - the user-requested push on that same branch
+- Do not duplicate commit-message or changelog-readiness logic inside this skill; post-merge archival must flow through `archive-specs`.
+- If a follow-up fix is required after verification or archival/doc sync, make that fix on the original current branch before handing off to `commit-and-push`.
 
-### 6) Report completion
+### 7) Report completion
 
-- List all branches that were merged.
+- List all child branches that were merged.
 - List any branches intentionally skipped because they were already merged, empty, or out of scope.
-- Confirm main is updated with all changes.
+- Confirm the original current branch is updated with all merged changes.
 - Note any conflicts that were resolved and the rationale.
 - Report the verification commands that were run.
+- Report whether `archive-specs` updated durable docs or found no archival/doc-sync work to do.
 - Confirm whether the workflow stopped at the local commit boundary or continued into a remote push because the user explicitly requested it.
 
 ## Working Rules
@@ -144,12 +161,13 @@ For each local branch (excluding main):
 - Never force-push; use only merge or rebase with merge.
 - Prefer preserving functionality over keeping either branch's exact changes.
 - Do not push to remote from this skill directly; let `commit-and-push` own any later publish step only when the user explicitly requests it.
+- Never merge parent branches, sibling branches, or unverified branches into the current branch; merge only branches whose child relationship to the original current branch is supported by git evidence.
 - If a branch contains no meaningful changes (empty merge), skip it.
-- Keep the main branch history clean and readable.
+- Keep the current branch history clean and readable.
 - If a branch's merge breaks tests, resolve the conflict differently before committing.
 - Do not stash or discard unrelated work automatically; stop when the working tree state makes the merge ambiguous.
 - Delete merged source branches and their detached worktrees only after the merge commit and verification both succeed.
-- When active batch specs provide merge-order guidance, follow that order unless new evidence proves the plan is stale or inapplicable; if so, stop and report the mismatch instead of silently overriding the batch plan.
+- When active batch specs provide merge-order guidance for in-scope child branches, follow that order unless new evidence proves the plan is stale or inapplicable; if so, stop and report the mismatch instead of silently overriding the batch plan.
 
 ## Conflict Resolution Examples
 
@@ -157,7 +175,7 @@ For each local branch (excluding main):
 |----------|---------------------|
 | Same line, both branches changed behavior | Read both code paths and compose the merged logic that preserves the verified invariant |
 | Same line, one branch is a bug fix and the other is a refactor | Keep the bug fix and reapply the compatible refactor structure manually if needed |
-| File deleted in branch, modified in main | Keep the version supported by current references/tests and remove only if the deletion is proven correct |
+| File deleted in branch, modified in current branch | Keep the version supported by current references/tests and remove only if the deletion is proven correct |
 | Both added same function differently | Keep both; rename if needed |
 | Config file conflict | Keep both values if non-overlapping |
 | Test file conflict | Keep both test cases |

package/merge-changes-from-local-branches/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Merge Changes from Local Branches"
-  short_description: "Merge relevant local branches into main with verified conflict resolution"
-  default_prompt: "Use $merge-changes-from-local-branches to inventory local branches, inspect active batch-spec `coordination.md` files under docs/plans and follow their documented merge order when present, merge only the relevant ones into local main, resolve conflicts by reading and composing the correct behavior instead of relying on blanket merge strategies, run targeted verification after conflictful merges, delete successfully merged source branches and detached worktrees only after verification succeeds, and leave remote state untouched."
+  short_description: "Merge verified child branches back into the current branch with checked conflict resolution"
+  default_prompt: "Use $merge-changes-from-local-branches to inventory the current branch plus any local child branches that verifiably forked from it, inspect active batch-spec `coordination.md` files under `docs/plans/` and follow their documented merge order when present, merge only those in-scope child branches back into the same current branch, resolve conflicts by reading and composing the correct behavior instead of relying on blanket merge strategies, run targeted verification after conflictful merges, run `archive-specs` so completed plan sets are archived and durable docs are synchronized before the final submit step, delete successfully merged source branches and detached worktrees only after verification succeeds, and leave remote publication to `commit-and-push`."

package/package.json

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