@laitszkin/apollo-toolkit 2.14.14 → 2.14.16

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+### Changed
+- None yet.
+
+## [v2.14.16] - 2026-04-11
+
+### Changed
+- Strengthen `generate-spec` so batch planning now requires spec sets to be truly parallel-implementable, not merely independently scoped.
+- Update `generate-spec` templates and prompts so `coordination.md` captures parallel-readiness gates, collision-resolution records, and pre-agreed ownership rules before concurrent implementation starts.
+
+## [v2.14.15] - 2026-04-11
+
+### Changed
+- Update `merge-changes-from-local-branches` so merge scope is determined from explicit branch names or spec-name mappings, instead of verifying child-branch ancestry from git history.
+- Update `implement-specs-with-worktree` so new worktree branches inherit from the same parent branch as the worktree base, and use the spec-set name as the canonical branch/worktree identifier.
+
 ## [v2.14.14] - 2026-04-11
 
 ### Changed

package/generate-spec/README.md

@@ -5,7 +5,7 @@ A shared planning skill for feature work. It centralizes creation and maintenanc
 ## Core capabilities
 
 - Generates single-spec plans under `docs/plans/{YYYY-MM-DD}/{change_name}/`.
-- Generates multi-spec parallel batches under `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` with a shared `coordination.md`, while keeping every batch spec independently completable.
+- Generates multi-spec parallel batches under `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` with a shared `coordination.md`, while keeping every batch spec independently completable and safe to implement concurrently.
 - Uses shared templates so spec-first and brownfield workflows follow the same planning structure.
 - Requires clarification handling and explicit user approval before implementation starts.
 - Backfills task and checklist status after implementation and testing.
@@ -84,11 +84,11 @@ 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, 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.
+- `coordination.md`: for multi-spec batches only, record shared preparation, ownership boundaries, replacement direction, file ownership guardrails, known collision candidates, pre-agreed edit rules for shared surfaces, 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
 
 - `scripts/...` and `references/...` are skill-folder paths, not project-folder paths.
 - The generator replaces `[YYYY-MM-DD]`, `[Feature Name]`, `[功能名稱]`, `[change_name]`, and `[batch_name]` placeholders.
-- If a batch split produces specs that must land in a functional sequence, re-slice the work so each spec becomes independently implementable, testable, and mergeable.
+- If a batch split produces specs that must land in a functional sequence, or still leaves unresolved shared-file collisions, re-slice the work so each spec becomes independently implementable, testable, mergeable, and parallel-safe before coding starts.

package/generate-spec/SKILL.md

@@ -15,9 +15,9 @@ description: Generate and maintain shared feature planning artifacts (`spec.md`,
 ## Standards
 
 - Evidence: Review the relevant code, configs, and authoritative docs before filling requirements or test plans; when external dependencies, libraries, frameworks, APIs, or platforms are involved, checking their official documentation is mandatory during spec creation.
-- Execution: Generate the planning files first, keep each spec set tightly scoped, split broader work into multiple independent spec sets when needed, ensure every batch spec is independently completable without depending on another spec set to land first, complete them with traceable requirements and risks, handle clarification updates, then wait for explicit approval before implementation.
+- Execution: Generate the planning files first, keep each spec set tightly scoped, split broader work into multiple independent spec sets when needed, ensure every batch spec is independently completable and truly parallel-implementable without depending on another spec set to land first, surface shared-file or shared-contract collision risks during planning, resolve those coordination rules before implementation starts, complete them with traceable requirements and risks, handle clarification updates, then wait for explicit approval before implementation.
 - Quality: Keep `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` synchronized, map each planned test to a concrete risk or requirement, and tailor the templates so only applicable items remain active.
-- Output: Store planning artifacts under `docs/plans/{YYYY-MM-DD}/{change_name}/` for single-spec work, or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` plus `coordination.md` for multi-spec parallel work whose member specs remain independently approvable and independently implementable, and keep them concise, executable, and easy to update.
+- Output: Store planning artifacts under `docs/plans/{YYYY-MM-DD}/{change_name}/` for single-spec work, or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` plus `coordination.md` for multi-spec parallel work whose member specs remain independently approvable, independently implementable, and ready for concurrent worktree execution with pre-agreed collision rules, and keep them concise, executable, and easy to update.
 
 ## Goal
 
@@ -47,6 +47,8 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Define those spec sets so they do not conflict with each other and do not require another spec set to land first in order to be approved or implemented safely.
 - For batch generation, treat cross-spec implementation dependency as a planning bug: if Spec B cannot be completed safely until Spec A lands, they should be one spec set or be re-sliced so each spec has its own self-contained outcome.
 - Allow shared preparation in `coordination.md` only when each spec can still complete that preparation or operate against an already-existing baseline without waiting for another spec's code changes.
+- Treat any unresolved shared-file collision, overlapping ownership, or incompatible contract change across spec sets as a planning bug to resolve before approval, not an implementation-time surprise.
+- If two candidate spec sets would still need to edit the same non-additive surface, either merge them into one spec set or record a concrete ownership split plus additive-only rule that makes parallel work safe.
 - Use:
   - `SKILL_ROOT=<path_to_generate-spec_skill>`
   - `WORKSPACE_ROOT=<target_project_root>`
@@ -93,7 +95,7 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Identify the affected modules, current baseline, proposed architecture, component responsibilities, control flow, data/state impact, and risk/tradeoff decisions.
 - Cross-reference relevant requirement IDs from `spec.md` and any external dependency records from `contract.md`.
 - Make architecture boundaries, invariants, and rollback/fallback expectations explicit when they matter to safe implementation.
-- When the spec belongs to a parallel batch, add a short reference to the parent `coordination.md` and keep `design.md` focused on the single-spec delta rather than duplicating cross-spec ownership rules.
+- When the spec belongs to a parallel batch, add a short reference to the parent `coordination.md`, state the exact assumptions that let this spec be implemented in parallel, and keep `design.md` focused on the single-spec delta rather than duplicating cross-spec ownership rules.
 
 ### 6.5) Fill `coordination.md` for parallel multi-spec batches
 
@@ -102,10 +104,12 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Use it as the batch-level source of truth for shared preparation, ownership boundaries, merge order, and cross-spec constraints.
 - Record explicitly that each spec set must remain independently completable and must not rely on another spec set's code changes, unfinished tasks, or merge order to achieve its own approved outcome.
 - Record shared fields, shared contracts, or shared data-shape preparation that multiple spec sets must align on before implementation starts.
+- Record whether the batch is ready for parallel implementation now; if not, list the blocking coordination items that must be settled before any spec 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 every known collision candidate, record the conflict shape, the pre-agreed owner or additive-only edit rule, and the trigger that requires re-coordination before implementation continues.
 - 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.
@@ -152,6 +156,7 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Never allow one spec set to cover more than three modules.
 - 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.
+- For batch specs, parallel readiness is also mandatory: each spec must be safe to implement concurrently, with shared-file collisions and ownership rules settled in `coordination.md` before coding begins.
 - 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.

package/generate-spec/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "generate-spec"
   short_description: "Generate shared feature spec, task, and checklist docs before coding"
-  default_prompt: "Use $generate-spec to create or update single-spec plans under docs/plans/<date>/<change_name>/ or parallel batches under docs/plans/<date>/<batch_name>/<change_name>/ with a shared coordination.md, but ensure every spec in a batch remains independently approvable and independently implementable without depending on another batch spec landing first; fill BDD requirements and risk-driven test planning, document external dependency contracts in contract.md when they materially constrain the change, write the architecture/design delta in design.md, record shared preparation and legacy-replacement direction in coordination.md when multiple specs will be implemented in parallel, process clarification updates, and wait for explicit approval before implementation."
+  default_prompt: "Use $generate-spec to create or update single-spec plans under docs/plans/<date>/<change_name>/ or parallel batches under docs/plans/<date>/<batch_name>/<change_name>/ with a shared coordination.md, but ensure every spec in a batch remains independently approvable, independently implementable, and safe for true parallel execution without depending on another batch spec landing first; surface shared-file or shared-contract collision risks during planning, settle ownership and additive-only rules in coordination.md before implementation starts, fill BDD requirements and risk-driven test planning, document external dependency contracts in contract.md when they materially constrain the change, write the architecture/design delta in design.md, process clarification updates, and wait for explicit approval before implementation."

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

@@ -6,6 +6,11 @@
 ## Coordination Goal
 [Describe the shared implementation goal across this batch of parallel spec sets.]
 
+## Parallel Readiness Gate
+- Ready for parallel implementation now: [Yes / No]
+- Blocking coordination items before coding: [None / list concrete ownership or contract decisions that must be settled first]
+- Re-coordination trigger: [what kind of new overlap or contract change forces the batch to stop and re-align]
+
 ## Batch Scope
 - Included spec sets: [[spec-name-1], [spec-name-2]]
 - Shared outcome: [what the batch delivers when all spec sets land]
@@ -23,6 +28,7 @@
 - Shared fields to introduce or reuse: [field / config / API shape / event schema]
 - Canonical source of truth: [which module or data owner defines them]
 - Required preparation before implementation: [migration, adapter, stub, flag, fallback, fixture]
+- Additive-only rule during batch: [what may be added safely without breaking parallel work, or `None`]
 
 ### Replacement / Legacy Direction
 - Legacy behavior being replaced: [feature / flow / module / endpoint / UI]
@@ -54,6 +60,22 @@
 - Merge order / landing order: [independent / optional convenience order only, never a functional prerequisite]
 - Worktree notes: [branch naming, rebase expectations, or `None`]
 
+## Collision Resolution Records
+
+### Collision 1: [Shared file / schema / manifest / contract]
+- Involved spec sets: [[spec-name-1], [spec-name-2]]
+- Conflict shape: [same file / same symbol / same schema field / same generated artifact]
+- Pre-agreed resolution: [single owner / additive-only edits / split by section / move into one spec]
+- Allowed edits per spec: [exact ownership boundary]
+- Escalation rule: [when engineers must stop and re-coordinate]
+
+### Collision 2: [Shared file / schema / manifest / contract]
+- Involved spec sets: [[spec-name-1], [spec-name-2]]
+- Conflict shape: [same file / same symbol / same schema field / same generated artifact]
+- Pre-agreed resolution: [single owner / additive-only edits / split by section / move into one spec]
+- Allowed edits per spec: [exact ownership boundary]
+- Escalation rule: [when engineers must stop and re-coordinate]
+
 ## Integration Checkpoints
 - Combined behaviors to verify after merge: [cross-spec outcome]
 - Required final test scope: [integration / E2E / migration / rollback]

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

@@ -17,6 +17,7 @@
 - Affected modules: [module/file/service list]
 - External contracts involved: [dependency names from `contract.md`, or `None`]
 - Coordination reference: [`../coordination.md` or `None`]
+- Parallel implementation assumption: [why this spec can be implemented concurrently, or `None` for single-spec work]
 
 ## Current Architecture
 [Describe the relevant current components, data flow, control flow, and boundaries.]
@@ -54,6 +55,7 @@
 - Key risks: [failure, concurrency, authorization, partial-write, dependency risk]
 - Rejected alternatives: [alternative + why it was not chosen]
 - Operational constraints: [performance, quota, observability, deployment coupling]
+- Cross-spec collision notes: [known shared-file/shared-contract collision avoided by ownership rules, or `None`]
 
 ## Validation Plan
 - Tests: [UT / PBT / IT / E2E / adversarial]

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

@@ -31,5 +31,6 @@
 - Task order should reflect actual implementation sequence.
 - Every main task must map back to `spec.md` requirement IDs.
 - Include explicit tasks for required test coverage (unit, regression, property-based, integration/E2E as applicable), mock scenario setup, and adversarial/edge-case hardening.
+- For batch specs, tasks must never include "wait for Spec X to land first" as a prerequisite; if such a dependency appears, re-slice the plan or move the coordination rule into `coordination.md`.
 - After execution, the agent must update each checkbox (`[x]` for done, `[ ]` for not done).
 - Remove all placeholder guidance text in square brackets after filling.

package/generate-spec/scripts/create-specs

@@ -48,7 +48,8 @@ def main() -> int:
         description=(
             "Create planning docs (spec.md, tasks.md, checklist.md, contract.md, design.md) "
             "from templates with folder format docs/plans/{date}/{change_name} "
-            "or docs/plans/{date}/{batch_name}/{change_name}."
+            "or docs/plans/{date}/{batch_name}/{change_name}, including coordination "
+            "templates for truly parallel-safe batch specs."
         ),
     )
     parser.add_argument("feature_name", help="Display name used in generated documents")
@@ -73,7 +74,8 @@ def main() -> int:
         action="store_true",
         help=(
             "When used with --batch-name, also create or update "
-            "docs/plans/{date}/{batch_name}/coordination.md from the shared template."
+            "docs/plans/{date}/{batch_name}/coordination.md from the shared template "
+            "for up-front ownership and collision coordination."
         ),
     )
     parser.add_argument(

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

@@ -6,9 +6,10 @@ description: >-
   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 main working tree. If not already in a worktree, create a new
-  worktree with an independent branch, implement all planned tasks, then commit
-  the changes to that local branch when complete.
+  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
@@ -22,14 +23,14 @@ description: >-
 
 ## Standards
 
-- 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.
+- Evidence: Read and understand the complete specs set before starting implementation, identify the authoritative parent branch that the worktree should inherit from, 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, create the worktree branch from the same parent branch as the worktree base, use the spec-set name as the canonical branch/worktree name, 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
 
-Implement approved spec planning sets in an isolated git worktree, ensuring main development is never interrupted by in-progress work.
+Implement approved spec planning sets in an isolated git worktree, ensuring the parent working tree is never interrupted by in-progress work.
 
 ## Workflow
 
@@ -58,18 +59,26 @@ 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.
+- 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
+  - do not default to `main` unless `main` is actually the parent branch of the worktree you are extending
 
 ### 3) Create a new worktree if needed
 
 If not already in a worktree, or if the user explicitly requests a fresh worktree:
 
-- Create a new branch for this implementation:
+- Derive the canonical spec name from the requested `change_name` directory.
+- Use that spec name as the shared branch/worktree identifier:
+  - branch name: `<type>/<spec-name>` following `references/branch-naming.md`
+  - worktree directory name: `<spec-name>`
+- Create a new branch for this implementation from the same parent branch identified in step 2:
   ```bash
-  git branch <branch-name> main
+  git branch <branch-name> <parent-branch>
   ```
 - Add a new worktree:
   ```bash
-  git worktree add ../<worktree-name> -b <branch-name>
+  git worktree add ../<spec-name> <branch-name>
   ```
 - Move into the new worktree directory and begin work there.
 
@@ -117,12 +126,14 @@ After implementation and testing:
 ### 7) Report completion
 
 - Summarize what was implemented.
-- Note the branch name and worktree location.
-- Confirm that main remains unaffected.
+- Note the spec-derived branch name and worktree location.
+- Confirm that the parent branch remains unaffected.
 
 ## Working Rules
 
-- Always work in an isolated worktree to keep main clean.
+- Always work in an isolated worktree to keep the parent checkout clean.
+- 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.
 - 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.

package/implement-specs-with-worktree/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Implement Specs with Worktree"
   short_description: "Implement an approved spec set inside an isolated git worktree"
-  default_prompt: "Use $implement-specs-with-worktree to read the full plan set under docs/plans, including parent coordination.md when the spec belongs to a parallel batch, create or reuse an isolated git worktree, implement all approved tasks within the shared ownership and replacement-direction constraints, backfill completion status into the planning docs, and commit the result to the local worktree branch without affecting main."
+  default_prompt: "Use $implement-specs-with-worktree to read the full plan set under docs/plans, including parent coordination.md when the spec belongs to a parallel batch, identify the parent branch that the worktree should inherit from, create or reuse an isolated git worktree whose branch and directory names are derived from the spec name, implement all approved tasks within the shared ownership and replacement-direction constraints, backfill completion status into the planning docs, and commit the result to the local worktree branch without affecting the parent branch."

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

@@ -1,16 +1,16 @@
 ---
 name: merge-changes-from-local-branches
 description: >-
-  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.
+  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.
 ---
 
 # Merge Changes from Local Branches
@@ -24,41 +24,43 @@ description: >-
 
 ## Standards
 
-- 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.
+- 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.
+- 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.
 
 ## Goal
 
-Consolidate verified child-branch changes back into the original current branch with automatic conflict resolution that preserves correct functionality.
+Consolidate the intended named local branches back into the original current branch with automatic conflict resolution that preserves correct functionality.
 
 ## Workflow
 
-### 1) Inventory the current branch and in-scope child branches
+### 1) Inventory the current branch and in-scope named 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.
 - 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.
+- Determine the in-scope branches directly from branch names:
+  - prefer the exact branch names the user provided
+  - otherwise map active spec-set names or documented merge-order entries to branch names
+  - otherwise stop and report the missing branch-name target instead of inferring from ancestry
+- Accept a branch as in scope only when its branch name can be matched unambiguously to the requested merge set; skip unrelated local branches.
 - 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
-  - Verified fork-point evidence from the current branch
+  - How the branch name was matched to the requested merge set
   - 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 only the in-scope child branches in the documented order when that order is explicit.
+- Map branch names to the corresponding spec sets or worktrees using the batch folder names, spec-set names, and documented merge-order entries; do not guess when the mapping is ambiguous.
+- Merge only the in-scope named 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.
+- If no active batch spec provides an explicit merge order, fall back to the requested branch-name list and merge the relevant branches sequentially in that explicit name order.
 
 ### 2) Ensure clean state on the original current branch
 
@@ -69,7 +71,7 @@ Consolidate verified child-branch changes back into the original current branch
 
 ### 3) Merge branches sequentially in the resolved order
 
-For each in-scope child branch:
+For each in-scope named branch:
 
 1. Check out the original current branch:
    ```bash
@@ -124,7 +126,7 @@ For each in-scope child branch:
 
 ### 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:
+- After a source 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>
@@ -148,7 +150,7 @@ For each in-scope child branch:
 
 ### 7) Report completion
 
-- List all child branches that were merged.
+- List all named branches that were merged.
 - List any branches intentionally skipped because they were already merged, empty, or out of scope.
 - Confirm the original current branch is updated with all merged changes.
 - Note any conflicts that were resolved and the rationale.
@@ -161,13 +163,13 @@ For each in-scope child branch:
 - 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.
+- Never merge unrelated or ambiguously matched branches into the current branch; merge only branches whose names are explicitly requested or can be matched unambiguously from the active spec context.
 - If a branch contains no meaningful changes (empty merge), skip it.
 - 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 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.
+- When active batch specs provide merge-order guidance for in-scope named 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
 

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "Merge Changes from Local Branches"
-  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`."
+  short_description: "Merge named local branches back into the current branch with checked conflict resolution"
+  default_prompt: "Use $merge-changes-from-local-branches to inventory the current branch plus the named local branches that should be merged, inspect active batch-spec `coordination.md` files under `docs/plans/` and follow their documented merge order when present, match the merge scope by branch name instead of branch ancestry, merge only those in-scope 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.14",
+  "version": "2.14.16",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",