@ngockhoale/ukit 3.4.61 → 3.4.62

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.62 - 2026-10-22
+
+**Handoff commands: state what `handoff.maxParallelAgents` counts (wording only).**
+- The cap is child workers of ONE batch or review set, summed across roles (implementers and reviewers together); the main session is outside it; it is not a session-wide limit; it is prompt-level guidance (no hook counts children) and the host's own concurrency limit is separate. Added to `handoff-implement`, `handoff-fullstack` (implement batch + review set) and `handoff-review`.
+- No default, config key, scope or behavior change. Basis: BAGuide field audit (peak 14 concurrent children while the cap text said 2, never refused), see `docs/analysis/CONCURRENCY-CHECKPOINT-2026-10-22.md`.
+
 ## 3.4.61 - 2026-10-22
 
 **omp bash: stop sending the call shape the host rejects (`name` + `async`/`timeout`).**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.61",
+  "version": "3.4.62",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/template_project/.claude/commands/ukit/handoff-fullstack.md

@@ -446,7 +446,7 @@ if it is missing required fields — never merely for sharing a file.
 **Batch each wave — mandatory.** Read `handoff.maxParallelAgents` from
 `.ukit/storage/config.json`. A wave with more tasks than that is split
 into consecutive batches of at most that many; finish one batch completely (including 3c
-copy-back and worktree deletion) before starting the next.
+copy-back and worktree deletion) before starting the next. The cap counts child workers of ONE batch/review set, summed across roles (implementers and reviewers together); the main session is outside it, and it is not a session-wide limit. It is prompt-level guidance: no hook counts children, and the host's own concurrency limit is separate.
 
 Never spawn a whole wide wave at once. Every background agent carries its own context
 window, and each finished report is injected back into this session — a wave of 20+ is
@@ -659,7 +659,7 @@ Never make fake edits or fake tests to satisfy an empty diff, and never lower ac
 
 ### R2 — Model isolation check (strong model, always first)
 
-**Batch the review set — mandatory.** Read `handoff.maxParallelAgents` from `.ukit/storage/config.json`. If more `pending_review` tasks exist than that, split into consecutive batches of at most that many; finish one batch's verdicts (R2–R4, appended to each task file) before starting the next.
+**Batch the review set — mandatory.** Read `handoff.maxParallelAgents` from `.ukit/storage/config.json`. If more `pending_review` tasks exist than that, split into consecutive batches of at most that many; finish one batch's verdicts (R2–R4, appended to each task file) before starting the next. The cap counts child workers of ONE batch/review set, summed across roles (implementers and reviewers together); the main session is outside it, and it is not a session-wide limit. It is prompt-level guidance: no hook counts children, and the host's own concurrency limit is separate.
 
 **Claude Code — MANDATORY, do this before anything else in R2–R4:** for each batch, call the Agent tool once per `pending_review` task **in parallel** (at most `handoff.maxParallelAgents`), each with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`, likewise invoked once per task in the batch, not once per wave). Reviewer agents only read the diff and append a verdict to their own task file — no worktree, no shared write target — so running them in parallel carries none of Phase 3's file-conflict risk. Do NOT review the diff yourself in the current session — this step is contracted to the strong tier (opus/unic-smart) and MUST differ from the executor's model, which only the spawned agent's frontmatter model guarantees.
 

package/template_project/.claude/commands/ukit/handoff-implement.md

@@ -103,7 +103,7 @@ when it is missing required fields — never merely for sharing a file.
 Read `handoff.maxParallelAgents` from `.ukit/storage/config.json`. A wave
 with more tasks than that is split into consecutive batches of at most that many; finish
 one batch completely (including 3c copy-back and worktree deletion) before starting the
-next.
+next. The cap counts child workers of ONE batch/review set, summed across roles (implementers and reviewers together); the main session is outside it, and it is not a session-wide limit. It is prompt-level guidance: no hook counts children, and the host's own concurrency limit is separate.
 
 Never spawn a whole wide wave at once. Every background agent carries its own context
 window, and each finished report is injected back into this session — a wave of 20+ is

package/template_project/.claude/commands/ukit/handoff-review.md

@@ -53,7 +53,7 @@ Classify by what the diff can show. An empty diff is NOT automatically "implemen
 
 ## Step 2 — Review the diff
 
-**Batch the review set — mandatory.** Read `handoff.maxParallelAgents` from `.ukit/storage/config.json`. If more `pending_review` tasks exist than that, split into consecutive batches of at most that many; finish one batch's verdicts (2a–2d, appended to each task file) before starting the next.
+**Batch the review set — mandatory.** Read `handoff.maxParallelAgents` from `.ukit/storage/config.json`. If more `pending_review` tasks exist than that, split into consecutive batches of at most that many; finish one batch's verdicts (2a–2d, appended to each task file) before starting the next. The cap counts child workers of ONE batch/review set, summed across roles (implementers and reviewers together); the main session is outside it, and it is not a session-wide limit. It is prompt-level guidance: no hook counts children, and the host's own concurrency limit is separate.
 
 **Spawn the review panel — MANDATORY, do this before anything else:** read `modelRoles['review-panel']` from `.ukit/storage/config.json` → `modelRoles` (default `['smart','code','lite']`; omp tier aliases `@smol`/`@default`/`@slow`). For each `pending_review` task in the batch, call the Agent tool **once per panel entry** (in parallel, bounded by `handoff.maxParallelAgents`), each with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`, likewise invoked once per panel entry per task) — each member bound to its panel tier and setting `PANEL_MEMBER: <tier>` in its verdict. Reviewer agents only read the diff and append a verdict to their own task file — no worktree, no shared write target — so running them in parallel carries none of Phase 3's file-conflict risk. Do NOT review the diff yourself in the current session — this step is contracted to the panel tiers and MUST differ from the executor's model, which only the spawned agent's frontmatter model guarantees. Pass each agent: the task file path, the executor's report, and the diff.