@laitszkin/apollo-toolkit 2.14.9 → 2.14.11

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [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
+- Strengthen `generate-spec` coordination guidance and template so parallel worktree batches must record file ownership guardrails, shared API or schema freeze rules, compatibility-shim retention rules, and post-merge integration checkpoints that reduce functional merge conflicts.
+- Update `implement-specs-with-worktree` so engineers executing batch specs must treat those `coordination.md` guardrails as blocking constraints during implementation instead of optional notes.
+
 ## [v2.14.9] - 2026-04-08
 
 ### Changed

package/generate-spec/README.md

@@ -84,7 +84,7 @@ docs/plans/<today>/membership-cutover/
 - `checklist.md`: use `- [ ]` only, adapt items to real scope, and record actual results.
 - `contract.md`: when external dependencies materially shape the change, record their official-source-backed invocation surface, constraints, and caller obligations in the standard dependency-record format.
 - `design.md`: record the architecture/design delta in the standard format, including affected modules, flow, invariants, tradeoffs, and validation plan.
-- `coordination.md`: for multi-spec batches only, record shared preparation, ownership boundaries, replacement direction, merge order, and cross-spec integration checkpoints, but never use it to make one spec depend on another spec's implementation before it can be completed.
+- `coordination.md`: for multi-spec batches only, record shared preparation, ownership boundaries, replacement direction, file ownership guardrails, shared API/schema freeze or additive-only rules, compatibility-shim retention rules, merge order, and cross-spec integration checkpoints, but never use it to make one spec depend on another spec's implementation before it can be completed.
 - If clarification responses change the plan, update the docs and obtain approval again before coding.
 
 ## Notes

package/generate-spec/SKILL.md

@@ -104,6 +104,11 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Record shared fields, shared contracts, or shared data-shape preparation that multiple spec sets must align on before implementation starts.
 - When one spec set replaces or removes legacy behavior, state that direction explicitly so all worktrees implement toward the same target rather than preserving the old behavior accidentally.
 - Capture which spec set may touch which modules, which files require coordination, and whether any landing order or cutover sequence must be respected.
+- Treat `coordination.md` as a merge-conflict prevention contract, not just a planning summary.
+- Record the concrete file ownership map, forbidden touch points, and shared files that require explicit coordination before edits begin.
+- For shared APIs, event schemas, config shapes, manifests, or artifact fields, record whether changes are additive-only during the batch and which spec set owns the canonical naming.
+- When temporary compatibility shims, adapters, or legacy bridges must survive until the whole batch lands, record that retention rule explicitly so one worktree does not remove a path another still depends on.
+- Record the post-merge integration checkpoints that must be re-verified after multiple worktrees land, especially when text merges may succeed while behavior still drifts.
 - If the batch still needs a recommended merge order, make that order operationally convenient rather than functionally required for any single spec to work correctly.
 - Keep single-spec concerns in that spec's own `design.md`; reserve `coordination.md` for batch-wide rules only.
 
@@ -148,6 +153,7 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - When a request exceeds that scope, split it into independent, non-conflicting, non-dependent spec sets before approval.
 - For batch specs, independence is mandatory: each spec must describe a complete slice that can be implemented, tested, reviewed, and merged without waiting for another spec in the same batch.
 - When multiple spec sets are created for one batch, keep their shared implementation direction in one `coordination.md` instead of duplicating cross-spec rules in every `design.md`.
+- For parallel worktree batches, make `coordination.md` specific enough that another engineer can tell which files they may edit, which shared contracts are frozen or additive-only, which shims must remain in place, and what combined behaviors need verification after merge.
 - Prefer realistic coverage over boilerplate: add or remove checklist items based on actual risk.
 - When external dependencies materially shape the change, `contract.md` is required and must capture the official-source-backed contract in the standardized record format.
 - `design.md` is required and must describe the architecture/design delta for the spec in the standardized format, even when the final design is intentionally minimal.

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

@@ -48,6 +48,9 @@
 
 ## Conflict Boundaries
 - Shared files requiring coordination: [file/module list or `None`]
+- File ownership / edit guardrails: [which spec set owns which shared files or `None`]
+- Shared API / schema freeze: [frozen owner + additive-only rule, or `None`]
+- Compatibility shim retention rules: [which adapters/flags/tests must remain until batch completion, or `None`]
 - Merge order / landing order: [independent / optional convenience order only, never a functional prerequisite]
 - Worktree notes: [branch naming, rebase expectations, or `None`]
 

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

@@ -75,6 +75,7 @@ Use branch naming from `references/branch-naming.md`.
 - Verify latest authoritative docs for involved stacks/integrations.
 - When `coordination.md` exists, respect its shared-field preparation, legacy-replacement direction, and allowed touch-point boundaries before editing.
 - Implement each task in `tasks.md` systematically.
+- When `coordination.md` defines file ownership guardrails, additive-only shared-contract rules, or compatibility-shim retention requirements, treat them as blocking execution constraints rather than optional guidance.
 - For each implemented change, add appropriate tests:
   - Unit tests for changed logic
   - Regression tests for bug-prone behavior
@@ -119,6 +120,7 @@ After implementation and testing:
 - Complete all planned tasks before committing; do not stop with partial work.
 - Treat the specs as the source of truth for scope — do not deviate without user approval.
 - When `coordination.md` exists, treat it as the source of truth for batch-level ownership and cutover direction.
+- Never remove a shared shim, rename a shared field, or rewrite a shared file outside the ownership map unless `coordination.md` explicitly allows that change or the user approves a coordination update first.
 - Follow the testing standards from `enhance-existing-features` and `develop-new-features`.
 - Do not push to remote unless the user explicitly requests it.
 

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.9",
+  "version": "2.14.11",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",