@ngockhoale/ukit 3.4.61 → 3.4.63

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.63 - 2026-10-22
+
+**Completion recovery: background pending is not a pipeline.**
+- Reproduced task `task-848c14831946f7c359cdf11faf45edd2` / `bk1n4wpks`: bare release verifier exited 0 in host notification; Bash/grep read did not ingest completion. Launch and masked-shell receipts share `exitStatusUnproven`; recovery falsely asserted pipeline and requested reruns.
+- Diagnostic-only fix: background launch -> wait SAME job, no duplicate; host completion -> Read task output through footer, not rerun; masked shell -> wrapper status unproven, actual pipe only a possible cause. Receipt acceptance/freshness unchanged; unsupported hosts remain fail-closed.
+- Regressions: pending, host completion+Bash vs Read, later launch not masking valid completion, failed runner, masked wrapper, analysis-doc freshness vs living STATUS; existing forged/mismatched/duplicate/foreign/stale controls retained.
+- Release-gate fixture repair: TERM-ignoring grandchild now signals readiness after handler installation before the measured runner deadline starts (injected real child); retains ≥700ms grace/escalation and no-survivor assertions. Production hook-process unchanged.
+- Independent four-task fixture pilot and whole-workflow budget proposal recorded; no paid pilot. OMP genuine-service live smoke remains unverified (deterministic RPC bash lacks name/ready); no claim of every-service coverage.
+
+## 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/manifests/documentation.yaml

@@ -462,6 +462,17 @@ entries:
     validation: [manual]
     archive_policy: replace-with-snapshot
     notes: continuity checkpoint for the concurrency audit (R6 corrections, bash guard, prepared unpaid pilot)
+  - id: docs-analysis-concurrency-pilot
+    path: docs/analysis/concurrency-pilot/README.md
+    class: canonical
+    audience: [owner, maintainer]
+    owner: runtime
+    source_of_truth: docs/analysis/concurrency-pilot/README.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: replace-with-snapshot
+    notes: independent frozen fixture pilot proposal; no paid run
   - id: docs-analysis-subagent-cost-audit
     path: docs/analysis/SUBAGENT-COST-AUDIT.md
     class: archive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.61",
+  "version": "3.4.63",
   "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.
 

package/template_project/.claude/ukit/runtime/execution-ledger.mjs

@@ -3268,7 +3268,9 @@ export async function recordExecutionReceipt({
     if (backgroundLaunchAck && receipt.success) {
       receipt.success = false;
       receipt.exitStatusUnproven = true;
-      noteUnprovenExitStatus(`${String(toolInput.command || '').trim().slice(0, 60)} (background launch)`);
+      if (ledgerMessageEmitter) {
+        try { ledgerMessageEmitter(`${JSON.stringify({ systemMessage: `UKit execution-ledger: background verification ${receipt.backgroundTaskId || '(unknown id)'} is pending. Wait for the same job; do not launch a duplicate. After the host task-notification, Read its tasks/<id>.output through the final exit footer to ingest completion; Bash/grep does not ingest it.` })}\n`); } catch { /* advisory */ }
+      }
     } else if (maskedStage && receipt.success) {
       receipt.success = false;
       receipt.exitStatusUnproven = true;
@@ -3605,7 +3607,15 @@ function recoveryInstruction(missingEvidence, ledger = {}, routeSummary = {}, {
     // Unproven never sets `verificationFailed`, so this must not key off that flag.
     const lastVerification = [...(ledger.receipts || [])].reverse().find((r) => r?.kind === 'verification');
     if (!instruction && lastVerification?.exitStatusUnproven === true) {
-      instruction = `The last verification (\`${String(lastVerification.command || '').slice(0, 80)}\`) ran in a pipeline, so its exit status is unproven. Re-run it without the pipe, or with \`set -o pipefail\`, and inspect the exit code.`;
+      if (lastVerification.backgroundTaskId && !lastVerification.backgroundCompletion) {
+        const id = lastVerification.backgroundTaskId;
+        const hostExit = hostCompletionExit(ledger.transcriptPath, id);
+        instruction = hostExit === null
+          ? `Background verification ${id} has no ingested completion (pending or unsupported host evidence). Wait for the same job and its host task-notification; do not launch a duplicate. Then use Read on its tasks/${id}.output through the final exit footer. Bash/grep does not ingest completion; a footer without a matching host notification is not proof.`
+          : `Background verification ${id} has host completion exit ${hostExit}, but no ingested completion receipt. Use Read on its tasks/${id}.output through the final exit footer (Bash/grep does not ingest completion). Do not rerun the completed job just to create evidence. If Read is rejected, check the matching launch, host notification, footer and output-file freshness; never fabricate a receipt.`;
+      } else {
+        instruction = `The last verification (\`${String(lastVerification.command || '').slice(0, 80)}\`) exit status is unproven: its shell wrapper may mask or skip the runner (a pipeline is one possible cause). Run the bare verification command and inspect its exit code; for an actual pipeline, propagate the runner status with \`set -o pipefail\`.`;
+      }
     }
     if (!instruction && ledger.verificationFailed) {
       instruction = 'Use the latest failed verification output, fix the failure, and rerun targeted verification.';