@laitszkin/apollo-toolkit 3.9.5 → 3.9.7

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to this repository are documented in this file.
 
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
+## [v3.9.7] - 2026-05-09
+
+### Changed
+
+- `merge-changes-from-local-branches`: restructure like `generate-spec` / `implement-specs` (Non-negotiables, Pause prompts, sample hints); drop mandatory `archive-specs` post-merge step; finalize via `commit-and-push` with local commit by default (push only when the user explicitly requests remote update); sync OpenAI agent `default_prompt`.
+
+## [v3.9.6] - 2026-05-09
+
+### Changed
+
+- `generate-spec`: refocus `design.md`/`contract.md` templates as coarse `INT-###`/`EXT-###` guiding context above `tasks.md` (avoid mirroring runnable checklist rows); tighten SKILL/README/agent prompt layering; clarify `tasks.md` notes accordingly.
+- `implement-specs`: treat `tasks.md` as the authoritative runnable queue; read `design`/`contract` as constraints/anchors; align execution standards copy.
+- `implement-specs-with-subagents`: remove fixed four-subagent ceiling and stagger-only pacing language; generalize parallel phase examples and agent prompt.
+- Root `README.md`: simplify `implement-specs-with-subagents` compatibility blurb.
+
 ## [v3.7.0] - 2026-04-29
 
 ### Added
@@ -29,11 +52,6 @@ All notable changes to this repository are documented in this file.
 - Simplify `maintain-project-constraints` to produce `AGENTS.md`/`CLAUDE.md` with exactly three sections: Common Development Commands, Project Business Goals, and Project Documentation Index
 - Update `archive-specs` to delegate documentation generation to the refactored `align-project-documents` and constraint-file refresh to `maintain-project-constraints`; replace flat-category reference templates with the new three-category structure
 
-## [Unreleased]
-
-### Added
-- (None yet)
-
 ## [v3.9.5] - 2026-05-08
 
 ### Changed

package/README.md

@@ -200,7 +200,7 @@ The install commands below were checked with the Skills CLI unless otherwise not
 Compatibility note:
 
 - `generate-spec` is a local skill used by `develop-new-features` and `enhance-existing-features`, and it can produce either a single spec set under `docs/plans/{YYYY-MM-DD}/{change_name}/` or a coordinated parallel batch under `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` with shared `coordination.md`.
-- `implement-specs-with-subagents` coordinates one `implement-specs-with-worktree` subagent per spec directory for approved multi-spec batches, with staggered launches and a maximum of four active implementation subagents.
+- `implement-specs-with-subagents` coordinates one `implement-specs-with-worktree` subagent per spec directory for approved multi-spec batches.
 - `recover-missing-plan` is a local skill used by `enhance-existing-features` and `ship-github-issue-fix` when a referenced `docs/plans/...` spec set is missing or archived.
 - `maintain-skill-catalog` can conditionally use `find-skills`, but its install source is not verified in this repository, so it is intentionally omitted from the table.
 - `read-github-issue` uses GitHub CLI (`gh`) directly for remote issue discovery and inspection, so it does not add any extra skill dependency.

package/generate-spec/README.md

@@ -12,7 +12,7 @@ A shared planning skill for feature work. It centralizes creation and maintenanc
 - Backfills task and checklist status after implementation and testing.
 - Keeps requirement, task, and test coverage mapping traceable.
 - Uses `test-case-strategy` to choose test levels, define meaningful oracles, and add focused unit drift checks to atomic implementation tasks.
-- Standardizes external dependency contracts in `contract.md` and architecture/design deltas in `design.md`.
+- Standardizes **`design.md` / `contract.md` as high-level context** (architecture + external truth, `INT-###`/`EXT-###` anchors)—**`tasks.md` remains the sole file-level execution queue** implementing that context.
 
 ## Repository layout
 
@@ -95,8 +95,8 @@ docs/plans/<today>/membership-cutover/
 - `spec.md`: use BDD keywords `GIVEN / WHEN / THEN / AND / Requirements`.
 - `tasks.md`: use `## **Task N: ...**` and atomic implementation queue items with allowed scope, output, completion condition, verification hook, and unit drift check.
 - `checklist.md`: use `- [ ]` only, adapt items to real scope, record actual results, and map behavior risks to test IDs plus oracles selected through `test-case-strategy`.
-- `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.
+- `contract.md`: cite-backed **facts/limits/security** + **`EXT-###` anchors** (coarser than **`tasks.md`**); **no parallel checklist**—task rows may cite `EXT-###` when useful.
+- `design.md`: architecture + coarse **`INT-###` ordering/coupling hints** for **authoring** **`tasks.md`**; **no file-level checkbox mirror**; vendor detail belongs in **`contract.md`**.
 - `coordination.md`: for multi-spec batches only, record 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.
 - `preparation.md`: optional batch-level prerequisite plan used only when specs cannot be made parallel-safe without prior shared work; keep it tasks-like, minimal, verified, and free of core business logic or target outcomes.
 - If clarification responses change the plan, update the docs and obtain approval again before coding.

package/generate-spec/SKILL.md

@@ -33,7 +33,7 @@ description: >-
 
 - **Evidence**: Official docs when externally constrained; record cites in `spec.md` / `contract.md`.
 - **Execution**: Scaffold → fill templates in place → clarification loop → approval gate → (later) backfill after implementation.
-- **Quality**: Synchronized artifacts; applicable template sections only; realistic checklist vs boilerplate (add/remove by risk); finalized docs read as an approved plan, not a fully checked starter; `contract.md` standardized records or honest `None` with reason.
+- **Quality**: Synchronized artifacts; **`tasks.md`** is unique runnable granularity; **`design.md`/`contract.md`** constrain and orient without mirroring checklist rows—**`TBD`/honest `None`** when facts missing.
 - **Output**: `docs/plans/{YYYY-MM-DD}/{change_name}/` or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/`; batch root `coordination.md` when intentionally parallel; `preparation.md` only when prerequisite batch work is required first.
 
 ## Workflow
@@ -60,7 +60,7 @@ apltk create-specs "<feature_name>" --change-name <kebab-case> --output-dir "$WO
 
 Multi-spec parallel batch: add `--batch-name <kebab-case>` and `--with-coordination`. **Only** if parallel safety needs prior shared work: add `--with-preparation`.
 
-Always materialize: `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md` from `references/templates/`. Add `coordination.md` / `preparation.md` at batch root only when flags require. Save under `docs/plans/{YYYY-MM-DD}/...`. After generation, fill in place **without** removing template headings unless truly N/A (document reason). Run a **template-drift pass** before approval: sections present, placeholders removed or justified.
+Always materialize: `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md` from `references/templates/`. Add `coordination.md` / `preparation.md` at batch root only when flags require. Save under `docs/plans/{YYYY-MM-DD}/...`. After generation, fill in place **without** stripping section headings unless truly N/A (document inline); drop unused repeatable blocks (extra component or dependency stubs). Run a **template-drift pass** before approval: required fields covered, placeholders removed or justified.
    - **Pause →** List the **module names** (≤3) this spec set will touch; if more, where is my **split plan**?
    - **Pause →** For every shared file two specs might touch, where is the **named** resolution in `coordination.md` or why is `preparation.md` required instead?
    - **Pause →** Did I run `apltk create-specs` from the **skill** context so template paths resolve correctly?
@@ -68,15 +68,16 @@ Always materialize: `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `desig
 ### 3) Author content (fill templates)
 
 - **`spec.md`**: Concrete scope; BDD (`GIVEN` / `WHEN` / `THEN` / `AND` / `Requirements`); testable requirements; boundaries, auth, failure, idempotency/concurrency/integrity where relevant; doc references; `3-5` clarification questions or `None`.
-- **`tasks.md`**: `## **Task N: [Title]**` with Purpose, Requirements, Scope, Out of scope; atomic `- N [ ]` lines obeying the triple requirement above; split tasks that exceed three files / multiple behavior slices / undocumented decisions; integrate `test-case-strategy` for test IDs and drift checks for non-trivial logic.
-- **`contract.md`**: One record per material external dependency (source, surface, I/O, limits, security, failures); else `None` + short reason—**no** fabricated deps.
-- **`design.md`**: Delta vs baseline; modules, responsibilities, flow, state, risks; cross-ref requirement IDs; parallel batch: pointer to `coordination.md`, assumptions for safe concurrency, **no** duplicating batch rules; with `preparation.md`, assume prep **done**—**do not** duplicate prep tasks.
+- **`tasks.md`**: `## **Task N: [Title]**` with Purpose, Requirements, Scope, Out of scope; atomic `- N [ ]` triple (path · change · verify). **Derive sequencing and decomposition from** **`spec.md` + `design.md` + `contract.md`**; **`tasks.md` stays the only enumerated runnable checklist**. Optionally cite **`INT-###` / `EXT-###`** on rows an anchor constrains—and **keep design/contract coarser**, never a second copy of checklist lines. Integrate `test-case-strategy` for drift checks where needed.
+- **`contract.md`**: Cite-backed **external facts / limits / failure semantics / security**, plus **`EXT-###`** integration **anchors** (typically fewer rows than **`tasks.md` items)—**constraints and anti-hallucination context**, **not** a parallel implementation runbook (`TBD` instead of guesses; **`Dependencies` → None** when genuinely no externals).
+- **`design.md`**: **High-level architectural context for composing `tasks.md`**—baseline/target shape, boundaries, modules, **`INT-###`** coarse coupling/order hints (`task` granularity lives only in **`tasks.md`**). No file-level chores; batches defer ownership grids to **`coordination.md`**; **`preparation.md`** assumed done—don't replay prep execution here.
 - **`coordination.md`** (batch root, parallel only): **Business Goals** (outcome, member specs, parallel readiness, exclusions, blockers → `preparation.md` or list); **Design Principles** (baseline, shared invariants, compat, cleanup—high level); **Spec Boundaries** → **Ownership Map** (allowed/forbidden touchpoints per spec) and **Collisions & Integration** (shared-file rules, freeze owners, merge order, checkpoints, re-coordination trigger)—**every** collision candidate **MUST** have a named resolution.
 - **`preparation.md`** (batch root, only if required): Preparation Goal (why, no core business logic, dependents, start condition); **Task P[N]** like `tasks.md` (atomic triple items); **Validation**; **Handoff** (assumptions, must-not-change, if prep changes later). Strip duplicate prep from member specs.
 - **`checklist.md`**: `- [ ]` adapted to scope; map behaviors to requirement/test IDs via `test-case-strategy`; behavior lines `[CL-xx]: … — R?.? → [Test IDs] — Result: …`; property-based logic **required** unless `N/A` + reason; honest execution/completion records—**no** checking unused examples or unchosen options.
    - **Pause →** Pick one **random** `tasks.md` checkbox: does it still fail the triple rule (target, change, verify)—if yes, rewrite now?
    - **Pause →** Does every **R** requirement ID I care about appear in `tasks.md` or `checklist.md` with a test or explicit `N/A`?
-   - **Pause →** For parallel batches, does `design.md` **avoid** duplicating what `coordination.md` already owns?
+   - **Pause →** Do **`design.md` / `contract.md`** stay **coarser than `tasks.md`** (no mirrored checkbox choreography / file paths)—yet still constrain ordering and forbidden hallucinations?
+   - **Pause →** For parallel batches, does `design.md` **avoid** duplicating batch ownership grids already locked in **`coordination.md`**?
 
 ### 4) Clarifications and approval
 
@@ -93,8 +94,8 @@ When implementation exists: mark `tasks.md`; sync `checklist.md` outcomes/`N/A`;
 ## Sample hints
 
 - **`tasks.md` line — bad**: `- [ ] Add tests` → **reject** (no path, change, verifier).
-- **`tasks.md` line — ok**:
-  `- [ ] src/auth/scope.rs — add deny-by-default matcher for unknown scopes · Verify: cargo test scope::defaults`
+- **`tasks.md` line — ok (with ledger wiring)**:
+  `- [ ] 2 src/api/handlers/oauth.rs — implement handler path for POST /oauth/token satisfying INT-003, INT-004 · EXT-001 client config loaded from env per contract · Verify: cargo test oauth::handlers::token_exchange`
 - **Batch scaffold** (three member specs): `WORKSPACE_ROOT=... apltk create-specs "OAuth batch" --change-name oauth-api --batch-name oauth-may-batch --with-coordination --output-dir "$WORKSPACE_ROOT/docs/plans"` (then repeat or use generator rules for additional `change-name` dirs as your tooling permits).
 - **`checklist.md` behavior row sketch**: `[CL-01]: invalid token rejected — R2.1 → TU-Scope-01,TU-Scope-02 — Result: pending`
 - **Split-trigger**: change touches `src/auth/*`, `src/cli/*`, `src/db/*`, `infra/terraform/*` (four modules) ⇒ **minimum two spec sets**, not one.

package/generate-spec/agents/openai.yaml

@@ -1,4 +1,6 @@
 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 shared coordination.md and, only when specs cannot be parallel-safe without prior shared work, a minimal non-business preparation.md; treat this skill's current references/templates/*.md files as the binding format even when older project specs use different layouts, ensure member specs assume preparation is already complete and do not duplicate its tasks, 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, use $test-case-strategy for risk-driven test planning and unit drift checks, make tasks.md an atomic implementation queue with concrete outputs and verification hooks, 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."
+  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 shared coordination.md and, only when specs cannot be parallel-safe without prior shared work, minimal non-business preparation.md; treat references/templates/*.md as binding format; member specs assume preparation finished—do not duplicate preparation tasks; surface collisions early and resolve ownership via coordination.md; fill BDD in spec.md; integrate $test-case-strategy into tasks/checklists.
+    **Critical layering:** design.md + contract.md are higher-level guiding context only (architecture + cite-backed external truth; coarse INT-### / EXT-### anchors). tasks.md MUST be the ONLY enumerated runnable queue with path-level edits and verification hooks—derive tasks FROM spec + design + contract WITHOUT mirroring checklist rows into design/contract; optionally cite INT/EXT on task lines for traceability—never duplicate task choreography inside design.md or contract.md.

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

@@ -4,62 +4,69 @@
 - Feature: [Feature Name]
 - Change Name: [change_name]
 
-## Purpose
-[Describe why external dependency contracts matter for this change.]
-
-## Usage Rule
-- Write one dependency record per external library, framework, SDK, API, CLI, platform service, or hosted system that materially constrains implementation.
-- If no external dependency materially affects the change, write `None` under `## Dependency Records` and briefly explain why this document is not needed for the current scope.
-- Every claim in this file must be backed by the official documentation or the verified upstream source actually used during planning.
-
-## Dependency Records
-
-### Dependency 1: [Dependency Name]
-- Type: [library / framework / SDK / API / CLI / hosted service / platform]
-- Version / Scope: [exact version, major line, API version, or `Not fixed`]
-- Official Source: [link]
-- Why It Matters: [what this dependency is responsible for in the change]
-- Invocation Surface:
-  - Entry points: [package import / endpoint / command / webhook / queue topic]
-  - Call pattern: [sync / async / streaming / webhook / batch / polling]
-  - Required inputs: [auth, headers, env vars, config keys, payload fields]
-  - Expected outputs: [return shape, side effects, emitted events, persisted state]
-- Constraints:
-  - Supported behavior: [documented supported modes relevant to this change]
-  - Limits: [rate limits, payload limits, timeout, ordering, pagination, size, quota]
-  - Compatibility: [runtime / platform / version / region / account constraints]
-  - Security / access: [auth model, scopes, permissions, secret handling]
-- Failure Contract:
-  - Error modes: [documented errors, degraded states, retries, eventual consistency]
-  - Caller obligations: [retry rules, idempotency keys, backoff, validation, cleanup]
-  - Forbidden assumptions: [what the implementation must not assume]
-- Verification Plan:
-  - Spec mapping: [R?.?]
-  - Design mapping: [section in `design.md`]
-  - Planned coverage: [UT / PBT / IT / E2E / mock scenario IDs]
-  - Evidence notes: [specific doc section or source snippet summary]
-
-### Dependency 2: [Dependency Name]
-- Type: [library / framework / SDK / API / CLI / hosted service / platform]
-- Version / Scope: [exact version, major line, API version, or `Not fixed`]
-- Official Source: [link]
-- Why It Matters: [what this dependency is responsible for in the change]
-- Invocation Surface:
-  - Entry points: [package import / endpoint / command / webhook / queue topic]
-  - Call pattern: [sync / async / streaming / webhook / batch / polling]
-  - Required inputs: [auth, headers, env vars, config keys, payload fields]
-  - Expected outputs: [return shape, side effects, emitted events, persisted state]
-- Constraints:
-  - Supported behavior: [documented supported modes relevant to this change]
-  - Limits: [rate limits, payload limits, timeout, ordering, pagination, size, quota]
-  - Compatibility: [runtime / platform / version / region / account constraints]
-  - Security / access: [auth model, scopes, permissions, secret handling]
-- Failure Contract:
-  - Error modes: [documented errors, degraded states, retries, eventual consistency]
-  - Caller obligations: [retry rules, idempotency keys, backoff, validation, cleanup]
-  - Forbidden assumptions: [what the implementation must not assume]
-- Verification Plan:
-  - Spec mapping: [R?.?]
-  - Design mapping: [section in `design.md`]
-  - Planned coverage: [UT / PBT / IT / E2E / mock scenario IDs]
-  - Evidence notes: [specific doc section or source snippet summary]
+> **Purpose:** **High-level external-dependency context for `tasks.md`**: cite-backed facts, limits, failures, security—so integrations are not hallucinated. **Not** a runnable checklist; **`tasks.md` executes** wiring (files, calls, mocks, tests). Internal coupling intent stays in **`design.md`** (`INT-###`).
+>
+> **Anti-duplication:** Do not enumerate per-file edits, checkbox steps, or copy task ordering. **`EXT-###`** are **constraints / anchors** that task rows may cite.
+>
+> **Undocumented gaps:** **`TBD`** + clarification—never invent payloads, endpoints, or semantics.
+
+## Scope
+
+- **External deps in this doc:** [`0` \| ≥1]
+- **`0`:** under **Dependencies** write **`None.`** plus one line (what “no deps” excludes for coders).
+
+## Dependencies
+
+If **external dep count is 0:** keep **only**:
+
+**None.** [one line — e.g. no network SDKs/APIs beyond stdlib/process]
+
+**Delete everything** from “### \[Dependency name]” downward.
+
+If **≥1 dependency:** delete the `None.` block above; copy one `### [Dependency name]` section per dependency.
+
+### [Dependency name]
+
+#### Evidence
+
+| Primary docs URL(s)             | Sections / anchors used |
+| ------------------------------- | ----------------------- |
+| […]                             | […]                     |
+
+**Version revision assumed:** [pinned \| line \| `Not fixed` — how pinning lands in **`tasks.md`**]
+
+#### Facts we rely on (must be citeable)
+
+| Fact / capability needed | Doc location |
+| ------------------------ | ------------ |
+| […]                      | […]          |
+
+#### Limits & failures (coding obligations)
+
+| Category                         | Doc fact | Meaning while executing **`tasks.md`** |
+| -------- | --------- | ---------------------------------------- |
+| Quotas · size · timeout · paging | […] | [backoff / batching — policy level] |
+| Errors / degraded modes | […] | [map-to-app policy—not file paths unless standard] |
+
+#### Security & secrets (policy level)
+
+| Concern           | Constraint |
+| ----------------- | ---------- |
+| Auth / scopes    | […]        |
+| Secret keys (names)| […]       |
+
+#### Integration anchors (`EXT-###`)
+
+**Grain:** Boundary truth + obligations—**fewer anchors than typical task rows**. Multiple checkboxes often satisfy one anchor.
+
+| ID        | What we integrate at this boundary *(doc-named surface)* | Non‑negotiables (handling, retries, idempotency *per doc*) | Forbidden assumptions |
+| --------- | ---------------------------------------------------------- | ----------------------------------------------------------- | --------------------- |
+| `EXT-001` | [endpoint · SDK symbol · topic — **verbatim-ish** from doc] | […]                                                        | […]                   |
+
+**Doc-level ordering constraint (if any):** [e.g. token before resource call—or `None`]
+
+#### Trace hooks (no task parroting)
+
+- Spec IDs covered: [R?.?]
+- Related **`design.md`** module keys / `INT-###`: [optional]
+- **Unknown / `TBD`:** [list or `None`]

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

@@ -4,65 +4,80 @@
 - Feature: [Feature Name]
 - Change Name: [change_name]
 
-## Design Goal
-[Describe the architecture/design objective for this spec change.]
-
-## Change Summary
-- Requested change: [one sentence]
-- Existing baseline: [current architecture or behavior relevant to the change]
-- Proposed design delta: [what will change structurally]
-
-## Scope Mapping
-- Spec requirements covered: [R?.?]
-- 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.]
-
-## Proposed Architecture
-[Describe the new or updated structure, ownership boundaries, and interaction flow.]
-
-## Component Changes
-
-### Component 1: [Name]
-- Responsibility: [what this component owns after the change]
-- Inputs: [events, params, payloads, config]
-- Outputs: [return values, writes, emitted events, calls]
-- Dependencies: [internal modules and external contracts]
-- Invariants: [business or technical rules that must hold]
-
-### Component 2: [Name]
-- Responsibility: [what this component owns after the change]
-- Inputs: [events, params, payloads, config]
-- Outputs: [return values, writes, emitted events, calls]
-- Dependencies: [internal modules and external contracts]
-- Invariants: [business or technical rules that must hold]
-
-## Sequence / Control Flow
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-## Data / State Impact
-- Created or updated data: [schemas, fields, caches, files, queues, config]
-- Consistency rules: [ordering, transactionality, idempotency, deduplication]
-- Migration / rollout needs: [if none, write `None`]
-
-## Risk and Tradeoffs
-- 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]
-- Contract checks: [how `contract.md` constraints will be validated]
-- Rollback / fallback: [how to contain or reverse impact]
-
-## Open Questions
-[Write `None` if the design is settled.]
-- [Question 1]
-- [Question 2]
+> **Purpose:** **High-level architectural context for `tasks.md`**—structure, coupling, sequencing intent—not a second implementation list. Requirement intent stays in `spec.md`; **documented vendor truth** stays in **`contract.md`**. **`tasks.md` owns** every runnable step (paths, edits, verifies).
+>
+> **Do not duplicate `tasks.md`:** no checkbox-style chores, no per-file implementation lines, no verifiers—the executable queue exists only under **`tasks.md`**. Optional **`INT-###`** labels are **coarse anchors** that task rows cite for traceability.
+>
+> **Audience:** Humans/agents authoring **`tasks.md`**, and implementers needing **mental model before** ticking task boxes—not a standalone execution script.
+
+## Traceability
+
+|                             |                                                                              |
+| --------------------------- | ---------------------------------------------------------------------------- |
+| Requirement IDs             | [R?.?]                                                                      |
+| In-scope modules (≤3)       | [paths / services]                                                           |
+| External systems touched    | [names only—full truth in **`contract.md`**, or `None`]                      |
+| Batch coordination          | [`../coordination.md` or `None`]                                            |
+
+## Target vs baseline
+
+|                       | Baseline (today) | Target (after this change) |
+| --------------------- | ---------------- | --------------------------- |
+| Structure / ownership | […]              | […]                         |
+
+## Boundaries
+
+- Entry surface(s): [HTTP · CLI · job · subscriber · FFI — whichever applies]
+- Trust boundary crossed: [`None` / brief]
+- Outside → inside (one line): `[Actor]` → `[our entry]` → `[…]` (vendor touchpoints **`contract.md` only`)
+
+## Modules (nouns only)
+
+| Module key | Responsibility (one sentence) | Owned artifacts (types, tables, queues) |
+| ---------- | ---------------------------- | ---------------------------------------- |
+| `[key]`    | […]                          | [none / list]                             |
+
+---
+
+## Interaction anchors (`INT-###`)
+
+**Grain:** **Above `tasks.md`**. One anchor ≈ a **meaningful handshake** between module keys—not one checkbox. Several task lines may realize a single `INT-###`.
+
+| ID        | Intent (when this coupling matters) | Caller → Callee | Coupling kind (route pattern · RPC · event · sync call—**name/pattern**, not file path) | Information / state crossing (summary) | Failure / propagation expectation (summary) |
+| --------- | ------------------------------------ | --------------- | ---------------------------------------------------------------------------------------- | -------------------------------------- | ------------------------------------------- |
+| `INT-001` | […]                                  | `A` → `B`       | […]                                                                                      | […]                                    | […]                                         |
+
+**Ordering / concurrency (design-level):** [parallelism rules, critical sections, or `None`—still no file-level steps]
+
+## Requirement linkage (coarse ordering)
+
+Maps **which `R` clusters** depend on **which anchor order**. **`tasks.md` decomposes** into concrete steps.
+
+### [Scenario / `R?.?` cluster]
+
+- Anchor order hint: `INT-…` → `INT-…` → …
+- Narrative glue (≤3 bullets): [why this order; what must not reorder]
+
+[`None` if one anchor suffices—say so]
+
+## Data & persistence (design-level)
+
+| Resource                      | Typical readers/writers (module keys) | Consistency expectation (ordering, idempotency) |
+| ----------------------------- | ------------------------------------- | ------------------------------------------------ |
+| [store · schema · queue …] | […]                                   | […]                                             |
+
+## Invariants (system-level)
+
+| Invariant | What breaks it architecturally           | Symptoms if violated |
+| --------- | ---------------------------------------- | -------------------- |
+| […]       | [coupling mistake / wrong owner / …]     | […]                  |
+
+## Tradeoffs inherited by implementation
+
+| Decision | Rejected alternative | Locks in (for **`tasks.md`**) |
+| -------- | -------------------- | ---------------------------- |
+| […]      | […]                  | […]                           |
+
+## Batch-only
+
+[`None` \| single line: responsibilities **not** in this spec → see **`coordination.md`**]

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

@@ -30,6 +30,8 @@ Out of scope: [files/modules/behaviors this task must not change]
   - Verify: [focused command/check/manual inspection; drift check ref if applicable]
 
 ## Notes
+- **Layering:** **`design.md`** / **`contract.md`** are **guiding context** only (architecture + external truth). **`tasks.md` is the sole numbered, file-level execution queue**—do not expect design/contract to re-list its checkboxes.
+- When drafting, derive task order and scope from **`spec.md`** + **`design.md`** + **`contract.md`**; optionally cite **`INT-###` / `EXT-###`** on rows those anchors constrain.
 - Task order reflects implementation sequence.
 - Every task must map back to `spec.md` requirement IDs.
 - Treat `tasks.md` as an implementation queue, not a summary.

package/implement-specs/SKILL.md

@@ -15,7 +15,8 @@ description: >-
 
 ## Non-negotiables
 
-- **MUST** read and understand the full in-scope planning set and the parent `coordination.md` when its path applies, **before** editing product code or tests for this spec. Read for meaning in this order: **`spec.md`** (requirements / intent), **`design.md`** (system design / boundaries), **`contract.md`** (external dependencies and interfaces), **`checklist.md`** (wrap-up, acceptance, and closing obligations), then treat **`tasks.md`** as the ordered implementation checklist. **MUST NOT** start coding until that read pass is complete for the current in-scope directory.
+- **MUST** read and understand the full in-scope planning set and the parent `coordination.md` when its path applies, **before** editing product code or tests for this spec. Read for meaning in this order: **`spec.md`** (requirements / intent), **`design.md`** (high-level architecture + coarse `INT-###` anchors—**guidance for structuring work**), **`contract.md`** (cite-backed external facts/constraints + `EXT-###` anchors), **`checklist.md`**, then treat **`tasks.md`** as **the authoritative ordered runnable checklist**. **MUST NOT** start coding until that read pass is complete for the current in-scope directory.
+- **MUST** execute **every** **`tasks.md`** line in listed order—the **executable source of truth** for what to ship. **`design.md` / `contract.md`** **inform** decomposition and forbid contradictions (**`INT-###` / `EXT-###`** when present are **constraints/anchors referenced from tasks**, not a second queue). **MUST NOT** silently wire alternate module flows or vendor surfaces that conflict with approved **`design`** / **`contract`**; resolve conflicts via **`generate-spec`** / explicit approved plan edits first.
 - **MUST** when multiple spec directories apply to one request, follow parent **`coordination.md`** merge / sequencing guidance (or the user’s explicit order if coordination is absent or defers to them) and **complete** one directory end-to-end—**all** of its `tasks.md` lines **and** **all** of its `checklist.md` wrap-up / acceptance work—**before** starting implementation work in the next directory. **MUST NOT** interleave partial implementation across sibling specs.
 - **MUST NOT** create a branch, switch branches, or add or use a `git worktree` for this work unless the user explicitly changes the request in the same conversation.
 - **`tasks.md` completeness (hard stop)**: **MUST** execute **every** actionable item listed in the in-scope `tasks.md` for this request—**no exceptions** for perceived size, duration, file count, refactor depth, or session length. **MUST NOT** stop early, “defer” unchecked tasks while claiming the spec is done, collapse multiple task lines into a partial summary, or substitute narrative progress for completing a remaining line. If a line is truly impossible under written contracts, **MUST** stop with evidence and **MUST NOT** treat the implementation pass as complete until the plan is amended through the governing planning workflow (`generate-spec` / user-approved update) and the revised `tasks.md` is then fully satisfied.
@@ -29,7 +30,7 @@ description: >-
 ## Standards (summary)
 
 - **Evidence**: Same as Non-negotiables: no coding until the spec set is fully read; no guessed plan paths.
-- **Execution**: Current checkout only; implement and test against the approved **`spec.md` / `design.md` / `contract.md`** and **`tasks.md`** lines—no parallel branch or worktree (unless the user rescopes to another skill).
+- **Execution**: Current checkout only; **`tasks.md`** defines runnable order and file targets; **`spec`/`design`/`contract`** constrain meaning and forbid contradictory wiring—implement and test until obligations are met—no parallel branch or worktree (unless the user rescopes to another skill).
 - **Quality**: **All** `tasks.md` lines **and** **all** `checklist.md` wrap-up / acceptance obligations for this scope satisfied (see Non-negotiables—workload is not an excuse); tests and checklist verifications executed as required; docs reflect reality; no scope creep into sibling specs.
 - **Output**: Current branch contains a clean, reviewable implementation of this spec only.
 

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

@@ -1,9 +1,9 @@
 ---
 name: implement-specs-with-subagents
 description: >-
-  Coordinator-only workflow for multispec batches: ingest `coordination.md`/`preparation.md`, run prerequisite work yourself, derive topological phases, launch ≤4 staggered **`implement-specs-with-worktree`** workers (one `{change}` each; **full** `tasks.md` + **full** `checklist.md` wrap-up—no partial handoff), **`merge-changes-from-local-branches`** after every phase succeeds, ledger every branch/test/merge—not for solo specs unless user explicitly insists on delegation overload. **Multi-phase: do not declare done until every non-blocked spec is merged across all phases** (or pipeline stopped on explicit blocker).
+  Coordinator-only workflow for multispec batches: ingest `coordination.md`/`preparation.md`, run prerequisite work yourself, derive topological phases, launch **`implement-specs-with-worktree`** workers (one `{change}` each; **full** `tasks.md` + **full** `checklist.md` wrap-up—no partial handoff), **`merge-changes-from-local-branches`** after every phase succeeds, ledger every branch/test/merge—not for solo specs unless user explicitly insists on delegation overload. **Multi-phase: do not declare done until every non-blocked spec is merged across all phases** (or pipeline stopped on explicit blocker).
   Wrong tool for one directory without parallel mandate—pick **`implement-specs-with-worktree`** / **`implement-specs`** depending on isolation. Publication/versioning stays outside this orchestration layer unless another skill attaches.
-  Ledger sample: `oauth-scope | phase=1 | merged | npm test ✅`. Burst-launching four agents simultaneously—disallowed pacing required…
+  Ledger sample: `oauth-scope | phase=1 | merged | npm test ✅`.
 ---
 
 # Implement Specs with Subagents (Multi-Phase)
@@ -22,7 +22,6 @@ description: >-
 - **MUST** complete, verify, and **finalize** documented shared preparation on the integration branch **through `commit-and-push`** before any implementation subagent starts when `preparation.md` exists or specs mandate pre-work; the coordinating agent **MUST NOT** delegate that preparation. Subagents **MUST NOT** start until this branch is clean at the preparation commit (or there is no required preparation).
 - **MUST** build a directed dependency graph from `coordination.md` plus each spec’s `spec.md` / `design.md` (edges: *provider spec must merge before consumer spec*). **MUST** partition specs into phases by topological **layers**: Phase 1 = specs with **no** in-batch prerequisites; for *k* ≥ 2, Phase *k* = specs whose in-batch prerequisites all appear in phases before *k*. **MUST NOT** start phase *k* until phase *k − 1* is fully merged into the integration branch (or you have an explicit user override). If the graph has a cycle, **MUST** stop and report it.
 - **MUST** assign **exactly one** spec directory per implementation subagent; **MUST NOT** assign multiple directories to one implementation subagent.
-- **MUST** cap **active** implementation subagents at **four**; **MUST** start them **one at a time** with confirmation each is running before the next start; **MUST** back off on rate limits (no burst launches). Four is a ceiling, not a quota.
 - **`tasks.md` + `checklist.md` completeness (hard stop)**: Every implementation subagent **MUST** finish **all** actionable items in its assigned directory’s `tasks.md` **and** **all** `checklist.md` wrap-up, acceptance, verification, and closing obligations before reporting success—**no** partial completion, **no** “good enough” stops for large batches, **no** deferrals disguised as done. The coordinating agent **MUST NOT** merge a phase branch, advance the ledger to **`merged`**, or treat a spec as complete while **any** in-scope `tasks.md` line **or** checklist-defined closing item remains undone unless the batch is explicitly **`blocked`** with documented user/contract halt. **MUST** repeat this mandate in **every** subagent envelope so workers cannot interpret scope loosely.
 - **MUST** give each subagent only task-local context (repo root, exact spec path, `coordination.md` path if relevant, instruction to run `implement-specs-with-worktree`, explicit **`tasks.md` full-completion** and **`checklist.md` wrap-up full-completion** requirements, baseline commit when preparation exists, requirement to read the full bundle before edits, worktree isolation, tests, backfill, local commit, and reporting branch/worktree/commit/tests/blockers). **MUST NOT** leak unrelated reasoning or other subagents’ private diffs unless resolving a concrete conflict.
 - After each phase: **MUST** merge every **completed** spec branch from that phase into the integration branch via `merge-changes-from-local-branches` before starting the next phase; **MUST** resolve conflicts using spec contracts as the correctness tie-breaker; **MUST** record merge result in the ledger; if merge is blocked, **MUST** stop the pipeline and report.
@@ -56,8 +55,8 @@ description: >-
    - **Pause →** Is there **exactly one** spec directory per queued subagent—never two in one prompt?
    - **Pause →** What will I **repeat** in every subagent envelope so they cannot “improvise” the wrong skill or wrong path?
 
-5. **Run phase *k*** — Start ≤4 subagents sequentially with task-local payloads (see Non-negotiables). Monitor ledger; pause new launches on shared blockers; on conflicting edits to shared files, resolve ownership using `coordination.md` before more launches; if one spec fails and others depend on it, **MUST NOT** start those dependents until resolved; batch-wide planning failure ⇒ stop all scheduling.
-   - **Pause →** How many subagents are **active** right now vs the cap of four; did I start the last one only **after** the previous was confirmed running?
+5. **Run phase *k*** — Launch subagents for each spec in the phase with task-local payloads (see Non-negotiables). Monitor ledger; pause new launches on shared blockers; on conflicting edits to shared files, resolve ownership using `coordination.md` before more launches; if one spec fails and others depend on it, **MUST NOT** start those dependents until resolved; batch-wide planning failure ⇒ stop all scheduling.
+   - **Pause →** Does every active subagent have a **distinct** spec directory assignment—no duplicate or overlapping paths?
    - **Pause →** Did two running subagents report **overlapping** paths; if yes, did I stop launching until ownership is clear?
 
 6. **Merge phase *k*** — When every item in phase *k* is **done or explicitly blocked**, merge **each successful** branch via `merge-changes-from-local-branches`; rerun critical tests if your standards say so; update ledger. Merge failure ⇒ **stop** before phase *k+1*. **“Done”** here **requires** full `tasks.md` completion **and** full `checklist.md` wrap-up / acceptance per Non-negotiables—not merely a subagent “looks finished” report.
@@ -78,9 +77,9 @@ description: >-
 
 ## Sample hints (subagent scheduling)
 
-- **Parallel batch (four independent specs)** — The batch contains **four** member directories and `coordination.md` allows parallel implementation with **no** in-batch prerequisites. Treat them as **one phase**: assign **exactly one** spec per subagent, start up to **four** **`implement-specs-with-worktree`** workers **staggered** (never burst—Non-negotiables), each finishing **all** of its directory’s **`tasks.md`** and **`checklist.md`** before reporting success; when **every** branch in the phase is green, run **`merge-changes-from-local-branches`** to bring **all four** into the integration branch **before** declaring the batch done or starting a follow-on phase.
+- **Parallel batch (independent specs)** — The batch has multiple member directories and `coordination.md` allows parallel implementation with **no** in-batch prerequisites. Treat them as **one phase**: assign **exactly one** spec per subagent, launch one **`implement-specs-with-worktree`** worker per spec, each finishing **all** of its directory’s **`tasks.md`** and **`checklist.md`** before reporting success; when **every** branch in the phase is green, run **`merge-changes-from-local-branches`** to bring **every** member into the integration branch **before** declaring the batch done or starting a follow-on phase.
 
-- **Preparation plus A → {B, C}** — Specs **A**, **B**, and **C** share a batch with **`preparation.md`**; `coordination.md` / design shows **B** and **C** depend on merged work from **A**. Coordinating agent: (1) complete **preparation** on the integration branch and **`commit-and-push`** (push only if the user asked); (2) **Phase 1**: launch **one** subagent for **A** only; **`merge-changes-from-local-branches`** for **A** when it passes; (3) **Phase 2**: launch **two** subagents for **B** and **C** from the branch that already contains **A**’s merge, still staggering starts; (4) merge **B** and **C** when both finish. **MUST NOT** start **B** or **C** until **A** is merged into the baseline they branch from.
+- **Preparation plus A → {B, C}** — Specs **A**, **B**, and **C** share a batch with **`preparation.md`**; `coordination.md` / design shows **B** and **C** depend on merged work from **A**. Coordinating agent: (1) complete **preparation** on the integration branch and **`commit-and-push`** (push only if the user asked); (2) **Phase 1**: launch **one** subagent for **A** only; **`merge-changes-from-local-branches`** for **A** when it passes; (3) **Phase 2**: launch **two** subagents for **B** and **C** from the branch that already contains **A**’s merge; (4) merge **B** and **C** when both finish. **MUST NOT** start **B** or **C** until **A** is merged into the baseline they branch from.
 
 - **Ledger reminder** — One row per spec remains mandatory (`phase`, `depends-on`, branch/worktree, `merged` / `blocked`, tests); see Non-negotiables for full fields.
 

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "Implement Specs with Subagents"
   short_description: "Coordinate parallel spec worktree implementations"
-  default_prompt: "Use $implement-specs-with-subagents to read coordination.md and any preparation.md first, complete and commit explicitly documented prerequisite preparation on the working branch before delegation, analyse spec dependencies to build a multi-phase plan, for each phase assign each approved docs/plans spec directory to one independent subagent that uses $implement-specs-with-worktree, launch at most four implementation subagents at once with staggered starts, after each phase use $merge-changes-from-local-branches to merge completed spec branches back into the working branch before launching the next phase, honor any requested model when supported, and track each branch, commit, test result, and blocker."
+  default_prompt: "Use $implement-specs-with-subagents to read coordination.md and any preparation.md first, complete and commit explicitly documented prerequisite preparation on the working branch before delegation, analyse spec dependencies to build a multi-phase plan, for each phase assign each approved docs/plans spec directory to one independent subagent that uses $implement-specs-with-worktree, after each phase use $merge-changes-from-local-branches to merge completed spec branches back into the working branch before launching the next phase, honor any requested model when supported, and track each branch, commit, test result, and blocker."

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

@@ -1,167 +1,114 @@
 ---
 name: merge-changes-from-local-branches
 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). After merge verification,
-  run `archive-specs` so completed plan sets are archived and durable project
-  docs are synchronized, then hand the current branch state to `commit-and-push`
-  so the final submit workflow commits and pushes on that same local branch.
-  Use when the user asks to consolidate local branch work, merge named branches
-  into the current branch, or prepare the current branch for integration.
+  Read changes from local branches identified by branch name and merge them back into the current local branch. Resolve conflicts by composing correct behavior (prefer the more recent change on the same line or the variant that preserves working behavior), using **`merge-conflict-resolver`** when needed. Verify after merges; remove successfully merged source branches and detached worktrees only after merge + verification succeed. Finalize through **`commit-and-push`** for submission-readiness gates and the **final local commit** on the same branch—**do not** push unless the user explicitly requested remote update in this thread (**`commit-and-push`** step 7). **Does not** run **`archive-specs`** as part of this skill.
+  Use when consolidating named local branch work into the current branch or preparing integration on that branch.
 ---
 
 # 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.
-- Conditional: `merge-conflict-resolver` to resolve merge conflicts deterministically when conflicts arise.
+- Required: **`commit-and-push`** for submission-readiness, mandated reviews, and the **final** commit on the original current branch (push **only** when the user explicitly asked for remote update in this thread—otherwise stop after commit).
+- Conditional: **`merge-conflict-resolver`** when merge conflicts require deterministic resolution.
 - Optional: none.
-- Fallback: If git operations fail, stop and report the error.
+- Fallback: If **`commit-and-push`** is unavailable, **MUST** stop and report—**MUST NOT** improvise readiness or use a bare `git commit` shortcut. If git merge operations fail irreparably, stop and report.
 
-## Standards
+## Non-negotiables
 
-- 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` after merge verification so completed plan sets are archived and durable docs are synchronized, then hand the final current-branch state to `commit-and-push` so changelog/readiness/commit/push work happens through the shared submission workflow on the same branch.
-- Quality: Never use blanket timestamp rules or default `-X ours/theirs` conflict resolution as the primary merge strategy, never infer in-scope branches from ancestry heuristics when branch names already define the target set, and do not declare success until the final current-branch state has been checked, verified, and cleared for post-merge archival/doc-sync work.
-- Output: Produce a clean current branch with all relevant named-branch changes integrated and ready for the shared submit workflow.
+- **MUST** treat the branch that was current at workflow start as the **authoritative merge target** for the whole workflow; **MUST NOT** silently switch the destination to **`main`** or another branch unless the user explicitly rescopes.
+- **MUST** determine in-scope branches from **explicit branch names** the user gives **or** from unambiguous mappings from active spec / `coordination.md` context—**MUST NOT** infer the merge set from ancestry heuristics alone when names already define intent.
+- **MUST** read active batch **`coordination.md`** when present and honor a documented **`Merge order` / landing order**; if multiple batches conflict or branch-to-spec mapping is ambiguous, **MUST** stop and report instead of guessing order.
+- **MUST** resolve conflicts by reading both sides and editing merged results that preserve shipped behavior—**MUST NOT** rely on blanket **`-X ours` / `-X theirs`** or timestamp guesses as the primary strategy.
+- **`archive-specs`**: **MUST NOT** invoke **`archive-specs`** from this skill. Any archival or doc-sync routing belongs to **`commit-and-push`** (via **`submission-readiness-check`**) when that workflow’s gates require it—not a separate mandated step immediately after merges here.
+- **MUST** verify the merged tree (targeted checks after conflictful merges; broader **`npm test` / equivalent** when the repo provides a standard command) before deleting source branches or handing off to **`commit-and-push`**.
+- **MUST NOT** **`git push`**, tag, or release **from this skill**; **`commit-and-push`** owns push **only** when the user explicitly requested remote publication in this thread (**same rule as **`commit-and-push`** step 7**).
+- **MUST** finalize through **`commit-and-push`** after staging the post-merge intent—**MUST NOT** bypass **`submission-readiness-check`** / mandated gates with a stray local commit path.
+- **MUST NOT** force-delete merged branches (**`-D`**) when **`-d`** refuses; **MUST** stop and report branches that are not actually merged into the target.
 
-## Goal
+## Standards (summary)
 
-Consolidate the intended named local branches back into the original current branch with automatic conflict resolution that preserves correct functionality.
+- **Evidence**: `git branch`, `git log` / diff stats vs current branch, conflict file contents, `coordination.md` merge order when present.
+- **Execution**: Inventory → clean target branch → sequential merges → verify → prune merged branches/worktrees → **`commit-and-push`** through local commit (push only if user asked).
+- **Quality**: Scope strictly to named / mapped branches; no unrelated branch sweeps; no push-by-default from this workflow.
+- **Output**: Integrated current branch ready for **`commit-and-push`**; concise report of merged/skipped branches, conflicts resolved, verification commands.
 
 ## Workflow
 
+**Chain-of-thought:** Before each numbered step, answer the **`Pause →`** prompts. Validator or verification red **blocks** advancing to pruning or **`commit-and-push`**.
+
 ### 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 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
-  - 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`)
+- Run `git branch`; capture `git branch --show-current` and `git status -sb`.
+- Inspect `docs/plans/` for active batch roots that include **`coordination.md`**; read merge-order guidance **before** choosing sequence.
+- Build the merge set from **user branch names**, else from unambiguous spec-name / **`coordination.md`** mappings—if a required name cannot be matched, stop and report.
+- For each candidate: `git log --oneline <current>..<candidate>` and `git diff --stat <current>...<candidate>` (or equivalent); skip empty / already-up-to-date branches and record why.
+- Per branch, note: name, match rationale, commits ahead, `git log -1 --oneline`.
+  - **Pause →** Is every in-scope branch matched **unambiguously**, not by “probably related” ancestry?
+  - **Pause →** If **`coordination.md`** gives a merge order, does my sequence match it literally?
 
 ### 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 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 requested branch-name list and merge the relevant branches sequentially in that explicit name order.
+- When **`coordination.md`** defines **`Merge order` / landing order**, merge **only** in that order after mapping branch names to specs/worktrees without guessing.
+- When multiple active batches disagree or mapping is unclear, stop and report.
+- When no explicit order exists, use the user’s branch list order sequentially.
+  - **Pause →** Would merging in a different order violate a written batch plan?
 
 ### 2) Ensure clean state on the original current branch
 
-- 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.
+- Inspect `git status`. If unrelated uncommitted changes block a safe merge, stop and report—**MUST NOT** stash or discard without user direction.
+  - **Pause →** Am I still on the **same** authoritative target branch I started with?
 
 ### 3) Merge branches sequentially in the resolved order
 
-For each in-scope named branch:
+For each in-scope branch:
+
+1. `git checkout <current-branch>`
+2. `git merge <branch-name> --no-ff -m "Merge branch '<branch-name>' into <current-branch>"`
+3. On conflicts: use **`merge-conflict-resolver`**; then `git add` resolved paths.
+4. If resolution is ambiguous, prefer behavior that preserves tests, documented intent, and minimal semantic drift.
+5. Complete the merge commit if Git did not auto-complete.
 
-1. Check out the original current branch:
-   ```bash
-   git checkout <current-branch>
-   ```
+### 4) Verify merged state
 
-2. Merge the branch:
-   ```bash
-   git merge <branch-name> --no-ff -m "Merge branch '<branch-name>' into <current-branch>"
-   ```
+- After conflictful merges, run the most relevant targeted tests or builds for touched areas.
+- After all merges, run the repo’s usual validation (`npm test`, `cargo test`, etc.) when applicable.
+  - **Pause →** Did verification fail? **MUST** fix on the current branch before pruning or **`commit-and-push`**—**do not** hide red tests behind a merge report.
 
-3. If conflicts occur, use $merge-conflict-resolver to resolve them deterministically.
+### 5) Prune merged sources (after verified success only)
 
-   After resolving files:
-   ```bash
-   git add <resolved-files>
-   ```
+- `git worktree list`; remove worktrees for successfully merged branches when safe.
+- `git branch -d <branch-name>` only for verified merges; refuse **`-D`** when **`-d`** fails—report instead.
+- **Never** delete the original target branch, the checked-out branch, or branches that failed / were skipped.
 
-4. If auto-resolution is ambiguous, prefer the change that:
-   - Does not break existing tests
-   - Preserves the documented feature intent
-   - Aligns with the code currently shipped on the source branch
-   - Minimizes hidden semantic drift between the merged modules
+### 6) Submit via **`commit-and-push`** (local commit; push optional)
 
-5. Complete the merge:
-   ```bash
-   git commit -m "Merge branch '<branch-name>' into <current-branch>"
-   ```
+- Stage the post-merge / fix-up intent per user scope.
+- Run **`commit-and-push`** through **commit**: inspect, classify gates, mandated reviews where applicable, **`submission-readiness-check`**, then commit with conventional message—**omit push** unless the user explicitly requested remote update in this thread ( **`commit-and-push`** step **7**).
+- **MUST NOT** reintroduce **`archive-specs`** as a sibling step controlled by **this** skill; if **`submission-readiness-check`** routes archival work, **`commit-and-push`** owns that decision.
+  - **Pause →** Am I about to push without an explicit user request for remote publication?
+  - **Pause →** Does `git diff --cached` match intended merge scope—no stray unrelated paths?
 
-### 4) Verify merged state
+### 7) Report
 
-- After each conflictful merge, run the most relevant targeted tests or build checks for the files that changed.
-- After all merges complete, run the repository's broader validation command when one exists:
-  ```bash
-  npm test  # or yarn test, cargo test, etc.
-  ```
-- If verification fails, fix the merged state on the current branch before proceeding.
-
-### 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`.
-- 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/CLAUDE.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 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>
-  ```
-- Delete only branches that were merged successfully:
-  ```bash
-  git branch -d <branch-name>
-  ```
-- If a branch still has an attached worktree, remove the worktree before deleting the branch.
-- Never delete:
-  - 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 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
-- 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`.
-
-### 7) Report completion
-
-- 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.
-- 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.
+- List merged vs skipped branches and why.
+- Current branch name; confirmation merges landed on original target.
+- Conflicts resolved and brief rationale.
+- Verification commands executed.
+- State whether completion stopped at **local HEAD** (**no push**) or included push per explicit user ask.
+
+## Sample hints
+
+- **Skip**: candidate shows no commits ahead of current—record “already merged / empty”.
+- **`coordination.md`**: landing order **`api-layer`** then **`cli-wrapper`** ⇒ merge matching branches in that sequence even if creation dates differ.
+- **`commit-and-push` without push**: user said “merge and commit locally”—run **`commit-and-push`** gates and commit; report `HEAD` hash; **no** **`git push`**.
 
 ## Working Rules
 
-- 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 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 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.
-
-Resolve conflicts using $merge-conflict-resolver.
+- Never force-push from this workflow.
+- Preserve functionality over winning either branch’s raw diff verbatim.
+- Do not merge ambiguously matched or unrelated branches.
+- Do not delete merged sources until merge commit **and** verification succeed.
+- When batch merge-order documentation applies, follow it unless you stop with evidence it is stale.
+
+Resolve conflicts using **`merge-conflict-resolver`**.

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "Merge Changes from Local Branches"
   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`."
+  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, delete successfully merged source branches and detached worktrees only after verification succeeds, then run $commit-and-push for submission-readiness and the final local commit on that branch without pushing unless the user explicitly requested remote update in the same thread. Do not invoke $archive-specs from this skill."

package/package.json

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