@laitszkin/apollo-toolkit 3.9.3 → 3.9.4

package/CHANGELOG.md

@@ -34,6 +34,11 @@ All notable changes to this repository are documented in this file.
 ### Added
 - (None yet)
 
+## [v3.9.4] - 2026-05-07
+
+### Changed
+- `implement-specs`, `implement-specs-with-worktree`, `implement-specs-with-subagents`: require full execution of every in-scope `tasks.md` line with no workload exemption; treat complete `checklist.md` wrap-up / acceptance / closing obligations as a hard gate before the spec may be considered done or merged (coordinators must not merge partial checklist closure); tighten workflow Pause prompts and agent-facing descriptions accordingly.
+
 ## [v3.9.3] - 2026-05-07
 
 ### Changed

package/implement-specs/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: implement-specs
 description: >-
-  Land an approved `docs/plans/{YYYY-MM-DD}/{change}` (or batch member path) on the currently checked-out branch: read the full planning bundle + `coordination.md` when relevant, execute every in-scope `tasks.md` item, backfill honest checklist/spec state, then **finalize through `commit-and-push`**—**do not** create branches/worktrees or widen to push/release unless the user explicitly asks mid-thread.
+  Land an approved `docs/plans/{YYYY-MM-DD}/{change}` (or batch member path) on the currently checked-out branch: read the full planning bundle + `coordination.md` when relevant, **execute every actionable line in `tasks.md` with no exemption for workload or session length**, **complete every `checklist.md` wrap-up / acceptance obligation so the spec is not “done” until checklist-backed closing work is satisfied**, backfill honest plan state, then **finalize through `commit-and-push`**—**do not** create branches/worktrees or widen to push/release unless the user explicitly asks mid-thread.
   Choose this for “implement on this branch” scenarios. If isolation is required use **`implement-specs-with-worktree`**; if multiple specs need delegated workers use **`implement-specs-with-subagents`**.
-  Good: stay on `feature/foo`, finish tasks, run **`commit-and-push`**. Bad: `git worktree add` purely to avoid dirty trees—wrong skill unless user re-scoped.
+  Good: stay on `feature/foo`, finish all `tasks.md` and `checklist.md` closing work, run **`commit-and-push`**. Bad: `git worktree add` purely to avoid dirty trees—wrong skill unless user re-scoped.
 ---
 
 # Implement Specs
@@ -19,7 +19,9 @@ description: >-
 
 - **MUST** read and understand the full in-scope planning set (`spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`) and the parent `coordination.md` when its path applies, **before** editing product code or tests for this spec.
 - **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.
-- **MUST** treat the approved `tasks.md` / contracts as the scope boundary: complete every item that is in scope for this request, run the relevant tests, and **MUST** backfill the planning documents with factual completion status (no aspirational checkboxes).
+- **`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.
+- **`checklist.md` wrap-up / acceptance (hard stop for “spec complete”)**: **MUST** complete **all** `checklist.md` obligations that constitute **wrap-up, acceptance, verification, release-prep, doc or index sync, or other closing/hand-off** work tied to this change—**same no-exemption bar as `tasks.md`** (workload, duration, or breadth **do not** waive checklist-only items). The **entire** in-scope spec is **not** **complete** until those checklist items are **actually satisfied** and truthfully marked. **MUST NOT** treat “implementation done” or proceed to final **`commit-and-push`** / completion reporting while checklist-defined closing work remains open or is waved away with narrative. If a checklist item is impossible under contracts or facts on the ground, **MUST** stop with evidence and **MUST NOT** declare the spec complete until the plan is amended through the governing workflow and the revised `checklist.md` is then fully satisfied.
+- **MUST** treat the approved `tasks.md`, `checklist.md`, and contracts as the scope boundary: on top of the rules above, run the relevant checklist-backed verifications and tests, and **MUST** backfill the planning documents with factual completion status (no aspirational checkboxes).
 - **MUST NOT** expand scope to unrelated sibling spec directories solely because they share a batch folder.
 - **MUST** finalize the implementation through **`commit-and-push`** after staging the intended change set (shared readiness, reviews per that skill’s classification, conventional commit message); **MUST NOT** complete the deliverable with a bare `git commit`, IDE-only commit, or other shortcut that skips **`submission-readiness-check`** / mandated gates.
 - **MUST NOT** `git push`, tag, or perform release steps **outside** **`commit-and-push`** (unless **`version-release`** / **`open-source-pr-workflow`** explicitly applies per user request).
@@ -29,7 +31,7 @@ description: >-
 
 - **Evidence**: Same as Non-negotiables: no coding until the spec set is fully read; no guessed plan paths.
 - **Execution**: Current checkout only; dependent-skill standards apply to all implementation and testing steps.
-- **Quality**: All in-scope tasks done; tests executed; docs reflect reality; no scope creep into sibling specs.
+- **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.
 
 ## Workflow
@@ -46,20 +48,22 @@ description: >-
    - **Pause →** What dirty paths are **out of scope**, and how will I avoid touching them inadvertently?
    - **Pause →** Is the integration target branch (where the user expects work) identical to what `git status -sb` shows?
 
-3. **Implement** — Execute approved `tasks.md` per `enhance-existing-features` / `develop-new-features`. Run relevant tests.
+3. **Implement** — Execute **the entire** approved `tasks.md` (every line) per `enhance-existing-features` / `develop-new-features`; do not close this step until **no** applicable unchecked tasks remain. Run relevant tests and **any** verification commands or artifact steps that `checklist.md` already assigns to the implementation phase (do not postpone checklist-only closing items that belong here).
+   - **Pause →** Have I listed **every** remaining `tasks.md` line—and is the count **zero** before I leave this step?
    - **Pause →** For the next task item, what is the **single** concrete change and its **single** primary verification—before I type code?
    - **Pause →** Am I about to touch a file that belongs to a **sibling** spec or an unrelated module without an in-scope task line?
    - **Pause →** After this chunk of work, which test command **proves** I did not break the contract’s stated behavior?
 
-4. **Backfill** — Update `checklist.md` / `tasks.md` (and any other plan files your standards require) so completion status matches what you actually did.
+4. **Backfill** — Update `checklist.md` / `tasks.md` (and any other plan files your standards require) so completion status matches what you actually did. **MUST NOT** advance to **Submit** until **every** checklist item that defines wrap-up or acceptance for this spec is **done** or the batch is an honest documented halt per Non-negotiables.
    - **Pause →** If I checked a box, can I point to **commit + test run** (or equivalent) that makes that check true—no wishful checking?
+   - **Pause →** Are **zero** checklist obligations that mean “before spec complete” still open—validated by re-reading `checklist.md`, not from memory?
    - **Pause →** Did any scope shrink or shift during implementation; if so, is the plan text updated **honestly**?
 
-5. **Submit** — Stage the intended implementation/backfill diff. Run **`commit-and-push`** through commit using that staged intent (and **push** only when the user explicitly requested remote update). Keep scope to this spec only; split into multiple submission passes only when an unavoidable checkpoint requires separate commits.
+5. **Submit** — Stage the intended implementation/backfill diff. Run **`commit-and-push`** through commit using that staged intent (and **push** only when the user explicitly requested remote update). Keep scope to this spec only; split into multiple submission passes only when an unavoidable checkpoint requires separate commits. **Only** reach this step when **both** `tasks.md` and `checklist.md` Non-negotiable closures are satisfied.
    - **Pause →** Does `git diff --cached` (or the equivalent staged view) show only this spec’s intended surface, or do I need to unstage/revert noise first?
    - **Pause →** Am I on the **same** branch I named in step 2, without a silent branch switch?
 
-6. **Report** — State current branch, commit hash, tests run, and which plan files were backfilled.
+6. **Report** — State current branch, commit hash, tests run, which plan files were backfilled, and explicit confirmation that **`tasks.md` and checklist-defined wrap-up work are complete** for this in-scope spec (or cite the documented blocker).
    - **Pause →** Would another engineer **reproduce** my conclusion from the branch name, commit hash, and test commands I listed alone?
 
 If this skill directory contains `references/implement-specs-common.md`, treat it as an optional extension to the steps above; if it is absent, the Workflow section here is authoritative.

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

@@ -1,7 +1,7 @@
 ---
 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), **`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 ≤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).
   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…
 ---
@@ -23,7 +23,8 @@ description: >-
 - **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.
-- **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`, 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.
+- **`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.
 - **Multi-phase completion**: When the planned ledger has **more than one** phase, **MUST** loop steps **5→6→7** until **every** in-scope spec is either **`merged`** on the integration branch or explicitly **`blocked`** with a documented stop (user abort, irresolvable conflict, failed dependency, etc.). **MUST NOT** yield, summarize as “phase complete”, or imply the batch is finished while **any** phase still has a successful, unmerged branch or **`pending`** / **`in_progress`** rows for specs that should run—unless the coordinating agent is halted by a preceding Non-negotiable blocker **and** that halt is stated plainly.
 - Model: If the user names a model, **MUST** use it for implementation subagents when the platform allows; if not supported, **MUST** state that fact and continue only if the default is acceptable to the user’s intent.
@@ -32,7 +33,7 @@ description: >-
 
 - **Evidence**: Batch read (`coordination.md`, `preparation.md`, every in-scope `spec.md` / `design.md`) before scheduling; ledger stays live.
 - **Execution**: Preparation → dependency graph → **repeat** (run phase *k* → merge phase *k*) until all phases reconciled on the integration branch; never skip merges between dependent phases; **multi-phase ⇒ no early “done” narrative** until ledger proves full merge-set (or documented blockers).
-- **Quality**: No duplicate delegation; subagents base on the branch that already contains preparation (and prior phases); pause on shared file collisions, batch-wide defects, or rate-limit pressure.
+- **Quality**: No duplicate delegation; subagents base on the branch that already contains preparation (and prior phases); **every** spec lands with **complete** `tasks.md` execution **and** **complete** `checklist.md` wrap-up, or a documented **blocked** state—workload is never a merge excuse; pause on shared file collisions, batch-wide defects, or rate-limit pressure.
 - **Output**: Concise ledger: per spec → phase, depends-on, subagent id/label, branch/worktree, commit or blocker, tests, merge status.
 
 ## Workflow
@@ -59,7 +60,8 @@ description: >-
    - **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?
    - **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*.
+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.
+   - **Pause →** For **each** spec I am about to merge, can I cite **evidence** (branch + `tasks.md` **and** `checklist.md` state) that **zero** applicable task lines **and** **zero** outstanding checklist closing items remain—or is this a documented **`blocked`** outcome instead?
    - **Pause →** Has **every** successful branch in this phase been merged into the **same** integration branch I will use to **start** phase *k+1*?
    - **Pause →** If a merge conflict touches a **contract** field, which spec’s `contract.md` / `design.md` is the tie-breaker I will apply?
 
@@ -78,7 +80,7 @@ description: >-
 
 - **Ledger row (one line per spec)**:
   `oauth-scope | phase=1 | depends-on: — | branch feat/oauth-scope | status merged | tests: npm test ✓`
-- **Subagent envelope (minimal)** — repo root `/repo`; spec `/repo/docs/plans/2026-05-01/batch-a/oauth-scope/`; instruction: run skill **`implement-specs-with-worktree`** on that path only; baseline `prep_sha=deadbeef` when preparation landed; reply with branch, `worktree path`, commit, tests.
+- **Subagent envelope (minimal)** — repo root `/repo`; spec `/repo/docs/plans/2026-05-01/batch-a/oauth-scope/`; instruction: run skill **`implement-specs-with-worktree`** on that path only; **mandate: complete every line in that directory’s `tasks.md` and every `checklist.md` wrap-up / acceptance item**; baseline `prep_sha=deadbeef` when preparation landed; reply with branch, `worktree path`, commit, tests, and confirmation that **no** applicable `tasks.md` items **or** checklist closing obligations remain open.
 - **Tiny dependency graph**: `api-layer` blocks `cli-wrapper` ⇒ Phase 1: `{ api-layer }`, Phase 2: `{ cli-wrapper }`. Independent specs share a phase layer (e.g. both in Phase 1) **only** if neither lists the other as prerequisite in spec/design/coordination.
 - **Launch cadence**: with cap 4, acceptable active counts over time: `1 → 2 → 3 → 4 → (finish one) → 4`; **not** spawn 4 in one burst with no pacing.
 

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

@@ -1,7 +1,7 @@
 ---
 name: implement-specs-with-worktree
 description: >-
-  Same contract as **`implement-specs`** but every write happens inside a dedicated `git worktree` + feature branch; verify `pwd` equals `git rev-parse --show-toplevel` before touching code; parent checkout remains read-only for deliverables; honor `preparation.md` baselines and sibling collision rules from `coordination.md`.
+  Same contract as **`implement-specs`**—including **complete execution of every `tasks.md` line and every `checklist.md` wrap-up / acceptance obligation regardless of workload**—but every write happens inside a dedicated `git worktree` + feature branch; verify `pwd` equals `git rev-parse --show-toplevel` before touching code; parent checkout remains read-only for deliverables; honor `preparation.md` baselines and sibling collision rules from `coordination.md`.
   Pick when the user or batch workflow demands isolation (“don’t disturb my dirty main”, per-spec worker). Plain same-branch edits stay on **`implement-specs`** instead.
   Good: commands show matching paths after `git worktree add ../oauth-scope feat/oauth-scope`. Bad: patching files under the primary checkout tree for implementation output.
 ---
@@ -23,7 +23,9 @@ description: >-
 - **MUST** use the spec directory name (`change_name`) as the canonical basename for the worktree path and branch stem; branch **`type`/name** must follow `references/branch-naming.md`.
 - **MUST** use `git show-ref` and `git worktree list --porcelain` (not shell guesses) when checking whether a branch or worktree already exists; if creation fails ambiguously, **MUST** re-query those commands before retrying.
 - When `preparation.md` exists: **MUST** treat it as an already-committed shared baseline for parallel work; **MUST NOT** redo its tasks inside the member spec unless the preparation commit is missing or the document states the prerequisite is still blocked. If baseline assumptions break, **MUST** update `preparation.md` or stop for coordination—**MUST NOT** silently move prerequisite work into the member spec.
-- **MUST** complete the same quality bar as `implement-specs`: all in-scope tasks, relevant tests, honest backfill, no sibling-spec scope creep, revert formatter-only noise outside owned files before commit.
+- **`tasks.md` completeness (hard stop)**: **MUST** satisfy the **`implement-specs` Non-negotiable** on **`tasks.md`**: execute **every** actionable line in the in-scope `tasks.md`, with **no** early exit for workload, duration, or breadth; partial task lists are **not** a mergeable or committable state. If a line cannot be met under contracts, **MUST** halt with evidence and resolve the plan through approved planning updates before claiming completion.
+- **`checklist.md` wrap-up / acceptance (hard stop for “spec complete”)**: **MUST** satisfy the **`implement-specs` Non-negotiable** on **`checklist.md`**: the spec is **not** **complete** and **must not** be merged or treated as finished until **all** checklist-defined wrap-up, acceptance, and closing obligations for the change are **done** and honestly recorded—**no** workload exemption.
+- **MUST** complete the same quality bar as `implement-specs`: on top of full `tasks.md` and **complete checklist wrap-up**, relevant tests, honest backfill, no sibling-spec scope creep, revert formatter-only noise outside owned files before commit.
 - **MUST NOT** `git push` **outside** **`commit-and-push`** unless the user explicitly requests remote update through that workflow (or a release/PR skill the user named).
 - For targeted Rust tests: **MUST** pass at most one positional `cargo test` filter per invocation; use separate commands or a broader confirmed filter when multiple selectors are needed.
 
@@ -31,7 +33,7 @@ description: >-
 
 - **Evidence**: Read full spec set plus `coordination.md` and `preparation.md` when present; verify whether the spec is already implemented on the baseline before opening a new worktree; if the plan is missing in the worktree, sync the authoritative copy and re-read before coding.
 - **Execution**: Isolated worktree only; branch naming per `references/branch-naming.md`; check sibling worktrees before editing shared boundaries in a parallel batch.
-- **Quality**: Same as `implement-specs`, plus collision awareness with sibling worktrees per `coordination.md`.
+- **Quality**: Same as `implement-specs` (including **all** `tasks.md` items **and** **all** `checklist.md` wrap-up obligations—no workload excuse), plus collision awareness with sibling worktrees per `coordination.md`.
 - **Output**: Clean local branch in the worktree with intended commits only; parent working tree unchanged by this implementation.
 
 ## Workflow
@@ -59,7 +61,7 @@ description: >-
 
 ### C) Implement, backfill, commit, report
 
-- Execute **`implement-specs` Workflow steps 3–6** (implement, backfill, **submit via `commit-and-push`**, report) **entirely from the worktree root**, applying `enhance-existing-features` / `develop-new-features` standards.
+- Execute **`implement-specs` Workflow steps 3–6** (implement—including **full** `tasks.md` and checklist-backed work per Non-negotiables—backfill—including **complete** `checklist.md` wrap-up before submit—**submit via `commit-and-push`**, report) **entirely from the worktree root**, applying `enhance-existing-features` / `develop-new-features` standards.
 - In the report, **MUST** include branch name, worktree path, commit hash, tests run, backfilled docs, and an explicit statement that the parent checkout was not modified for implementation files.
   - **Pause →** Am I honoring **implement-specs** step 3–6 **constraints** literally while respecting that all writes happen **only** under this worktree root?
   - **Pause →** If I used Rust `cargo test` filters, did I violate the **single positional filter** rule; how would I split the commands?

package/package.json

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