@ngockhoale/ukit 2.5.1 → 2.6.2

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

@@ -66,9 +66,10 @@ numbered step completes:
 Command: handoff-fullstack
 Goal: <one sentence from the **Problem / feature** section above>
 Base: <BASE branch>
-Phase: <P1|P2|P2.5|P3|I1|I2|I3|I4|R1|R2|R3|R4|R5|done>
+Phase: <P0|P1|P2|P2.5|P3|I1|I2|I3|I4|R1|R2|R3|R4|R4.5|R5|F|done|blocked>
 Cursor: wave <N> batch <M> — <what just finished>
 Next: <the exact next step to run>
+QuietScans: <n>/<required>   # only while sweeping for stragglers near the end
 ```
 
 This file is the resume contract. It costs one small write per step and is what turns an
@@ -76,13 +77,99 @@ interrupted run into a continuable one.
 
 ### Resume — when the run is re-invoked mid-flight
 
-If `docs/AI_HANDOFF/RUN.md` exists with `Phase:` not `done`, this is a **continuation, not a
-new cycle**. Do NOT re-plan, do NOT overwrite `PLAN.md`, do NOT ask the human whether to
-continue. Read the cursor, then jump straight to `Next:` and carry on. Tasks already `done`
-or `pending_review` are skipped; only `ready`, `in_progress`, `changes_requested` and
-`blocked` tasks are picked up.
+If `docs/AI_HANDOFF/RUN.md` exists with `Phase:` not `done` or `blocked`, this is a
+**continuation, not a new cycle**. Do NOT re-plan, do NOT overwrite `PLAN.md`, do NOT ask
+the human whether to continue. Read the cursor, then jump straight to `Next:` and carry on.
+Tasks already `done` or `pending_review` are skipped; only `ready`, `in_progress`,
+`changes_requested` and `blocked` tasks are picked up.
 
-Only when `RUN.md` is absent or `Phase: done` does a new request start a fresh cycle.
+`Phase: blocked` is terminal for the run — the machinery (Stop gate, hooks, stop-coordinator)
+all treats it as closed. It is *paused*, not abandoned: an explicit `/ukit:handoff-fullstack`
+re-invocation resumes it as a continuation; `ukit handoff-clear` abandons it. Only when
+`RUN.md` is absent or `Phase: done` does a new request start a fresh cycle.
+
+---
+
+## §0 — Completion contract (terminal outputs)
+
+This run has exactly **two** legal ways to end:
+
+- `HANDOFF FULLSTACK COMPLETE` — the completion gate in Phase F passed. First line of the
+  final report, verbatim.
+- `HANDOFF FULLSTACK BLOCKED` — every remaining task depends on the same external blocker
+  (missing credential, dead service, permission wall) AND no safe local work exists. Write
+  `Phase: blocked` to RUN.md before emitting it so the Stop gate releases the session.
+
+Nothing else ends the run. A recap is a progress notification, not a stopping point. If you
+emit a checkpoint it MUST use this shape and be followed by immediate work:
+
+```
+CHECKPOINT — WORK CONTINUING
+Cycle:
+Completed since last checkpoint:
+Currently executing:
+Exact next action:
+Verification status:
+Run cursor updated: YES
+```
+
+Never stop at `recap: ... Next: ...` while unfinished work remains — the Stop gate now
+bounces that stop straight back into the pipeline, so stopping is not even restful; it
+just costs a round-trip.
+
+---
+
+## Phase 0 — Sweep & Inventory (before planning)
+
+Before Phase 1, build the authoritative task inventory — the run owns **all** unfinished
+work, not only the current plan:
+
+1. `docs/AI_HANDOFF/INDEX.md` — every task not `done`/`cancelled_superseded`.
+2. `docs/AI_HANDOFF/tasks/TASK-*.md` — stale `in_progress` from a dead session, `blocked`,
+   `changes_requested`, `needs_executor_report`, `needs_breakdown`.
+3. Previous cycles — `docs/AI_HANDOFF/HISTORY.md` and `archive/` for cycles closed with
+   unfinished tasks; their leftovers join THIS cycle.
+4. `docs/TASKS.md` — `Ready for AI` items are newly-assigned work; fold them into the plan.
+5. `git status` / `git diff` — uncommitted work-in-progress that must be finished or
+   checkpointed, never silently dropped.
+
+The inventory feeds P2: the planner either schedules every discovered item or records why
+it is out of scope (§1/§2 of PLAN.md). Silent omission is a plan defect.
+
+**Recovery rule — stuck task records.** For every `pending`, stale `in_progress`, or
+`blocked` task whose record cannot be cleanly resumed (invalid state, orphaned worktree
+gone, contradicting reports):
+
+1. Inspect code/tests/git to see what is actually missing.
+2. Recoverable → finish the original task in place.
+3. Not recoverable → mark the old row `cancelled_superseded`, create `TASK-xxx-R1`
+   (`-R2`, …) with the same spec references, acceptance criteria and verification, link
+   both files' `## Discussion` threads, and execute the replacement in this cycle.
+4. Never leave stranded work merely because a task record was pending.
+
+---
+
+## Watchdog — surviving idle and new assignments
+
+The run must keep itself alive without the human watching.
+
+- **Stop gate (Claude Code, automatic):** while `RUN.md` `Phase:` is not `done`/`blocked`,
+  `completion-gate.sh` refuses the stop with the cursor's `Next:` step. Recaps and
+  premature stops cannot park the run. A stalled-cursor breaker
+  (`handoff.fullstack.stopGateMaxStalledBlocks`, default 12) releases the session if the
+  cursor has genuinely stopped advancing — the escape hatch, not the norm.
+- **Scheduled wakeup (when the harness offers one):** arm it at run start — Claude Code:
+  `CronCreate` a ~`handoff.fullstack.idleWatchdogMin`-minute (default 5) session job with
+  prompt `Resume HANDOFF FULLSTACK from docs/AI_HANDOFF/RUN.md — continue the Next: step`;
+  `/loop`-style tools: the equivalent interval. Cancel/let it expire once `Phase: done`.
+- **Harnesses with neither:** treat EVERY activation as a watchdog recovery turn — read
+  RUN.md first, rescan the inventory, continue `Next:`.
+
+**Quiet-period rule.** The run may finish only after the backlog is empty AND
+`handoff.fullstack.quietScansRequired` (default 2) consecutive watchdog scans find no new
+assignment, no recoverable task, and no uncommitted intended change. Record each quiet
+scan in RUN.md as `QuietScans: <n>/<required>`. A scan that finds anything resets the
+counter and starts a new cycle automatically.
 
 ---
 
@@ -117,7 +204,15 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
    BASE=$(git symbolic-ref --short HEAD)
    ```
 
-3. **Write `docs/AI_HANDOFF/PLAN.md`** — all 6 sections mandatory:
+3. **Write `docs/AI_HANDOFF/SPEC.md`** — the detailed implementation spec, from
+   `templates/docs/AI_HANDOFF/SPEC.md`'s section list (or RULES.md §Spec). It must be
+   concrete enough that an executor implements without guessing: exact paths, module and
+   API names, schemas, validation rules, permissions, empty/error states, migration
+   behavior, and test expectations — every applicable section filled, open questions
+   resolved to chosen defaults recorded inline. Implementation begins from SPEC+PLAN,
+   never from the raw request.
+
+4. **Write `docs/AI_HANDOFF/PLAN.md`** — all 6 sections mandatory:
    - §1 Intent — problem + success definition
    - §2 Scope — in / out of scope; same-wave tasks must not modify the same file (prevents merge conflicts)
    - §3 Approach — solution, trade-offs, alternatives rejected
@@ -131,8 +226,9 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
    PLANNER_MODEL: <your exact model ID>
    ```
 
-4. **Create `docs/AI_HANDOFF/tasks/TASK-001.md`, `TASK-002.md`...** from `_TEMPLATE.md`.
+5. **Create `docs/AI_HANDOFF/tasks/TASK-001.md`, `TASK-002.md`...** from `_TEMPLATE.md`.
    Every task MUST have:
+   - Spec references (SPEC.md section IDs this task implements)
    - Target Files (exact paths — no two tasks in same wave share a file)
    - Dependencies (`TASK-xxx` or `none` — wave structure inferred from this)
    - Test Cases (Type | Name | Expected — ≥1 happy + ≥2 edge cases of different kinds)
@@ -141,17 +237,21 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
    - Acceptance Criteria (verifiable checklist)
    Missing any field → status `needs_breakdown`, never `ready`.
 
-5. **Update `docs/AI_HANDOFF/INDEX.md`** — one row per task, `status=ready`.
+6. **Update `docs/AI_HANDOFF/INDEX.md`** — one row per task, `status=ready`. Every
+   unfinished item from the Phase 0 sweep is either a row here or superseded by a
+   `-R<n>` recovery row.
 
-6. **Update `docs/AI_HANDOFF/ACTIVE.md`:**
+7. **Update `docs/AI_HANDOFF/ACTIVE.md`:**
    ```
    Cycle: <ID>   Date: <YYYY-MM-DD>   Base: <BASE>
    Goal: <1 sentence>
+   Spec: docs/AI_HANDOFF/SPEC.md
    Tasks: <N> total
    Status: planning_done — ready for executor
    ```
 
-7. **Report:** task IDs, dependency graph, any `needs_breakdown` tasks + reason.
+8. **Report:** task IDs, dependency graph, recovery/superseded tasks, any
+   `needs_breakdown` tasks + reason.
 
 ### P2.5 — Independent plan review (strong model, separate agent)
 
@@ -164,9 +264,9 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
 The gate still does its job — two independent opus passes shape the plan before a line of code
 is written. What it no longer does is hand a stalled plan back to a human who isn't there.
 
-**Claude Code — MANDATORY, do this before anything else in P2.5:** call the Agent tool with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`), passing `REVIEW_TARGET_TYPE=plan` and the path to `docs/AI_HANDOFF/PLAN.md`. This MUST be a separate agent invocation from P2's `handoff-planner` call (fresh context) — same-session self-review defeats the purpose of an independent gate.
+**Claude Code — MANDATORY, do this before anything else in P2.5:** call the Agent tool with `subagent_type: "code-reviewer"` (omp: the `task` tool with `agent: "code-reviewer"`), passing `REVIEW_TARGET_TYPE=plan` and the paths to `docs/AI_HANDOFF/PLAN.md` AND `docs/AI_HANDOFF/SPEC.md`. This MUST be a separate agent invocation from P2's `handoff-planner` call (fresh context) — same-session self-review defeats the purpose of an independent gate.
 
-1. Reviewer reads `PLAN.md` only (no diff, no task files, no executor report), checks Completeness / Consistency / Clarity / Scope / YAGNI — see `.claude/agents/code-reviewer.md` → Spec/Plan Review — and appends its verdict to PLAN.md's `## Plan Review Log` (new round entry, prior rounds kept).
+1. Reviewer reads `SPEC.md` + `PLAN.md` only (no diff, no task files, no executor report), checks Completeness / Consistency / Clarity / Scope / YAGNI plus the spec quality gate — every requirement testable, every fullstack layer covered, dependencies explicit, legacy sweep included, no vague instruction left ("improve UI" without defined behavior fails) — see `.claude/agents/code-reviewer.md` → Spec/Plan Review — and appends its verdict to PLAN.md's `## Plan Review Log` (new round entry, prior rounds kept).
 2. `Issues Found` → route back to P2: `handoff-planner` revises `PLAN.md` and the affected `TASK-xxx.md` files to address every finding, then re-submit for one more P2.5 review round — subject to the loop cap above.
 3. `Approved` → append `PLAN_REVIEW: Approved by <reviewer model>` to PLAN.md's `## Planner Report` footer, then proceed to P3.
 
@@ -510,9 +610,50 @@ Force-push stays denied, so this can only ever fast-forward.
 
 **If some tasks are `blocked`:** still push. The approved work is reviewed, tested, and
 committed; withholding it helps no one, and the per-wave commits make any subset revertible.
-Name the blocked tasks in the Final Report.
+Name the blocked tasks in the Final Report. Tasks that stayed `blocked` only because their
+record was unrecoverable get the Phase 0 recovery treatment — `cancelled_superseded` plus a
+`-R<n>` replacement — before the run may close.
+
+Do NOT set `Phase: done` yet — Phase F still has to close the books.
+
+---
+
+## Phase F — Finalize: quiet period, docs, archive
+
+### F1 — Quiet-period scan
+
+Run the sweep from Phase 0 again (INDEX, task files, `docs/TASKS.md`, git status).
+`handoff.fullstack.quietScansRequired` (default 2) consecutive scans must each find:
+no unfinished task, no new assignment, no uncommitted intended change. Record each scan
+in RUN.md (`QuietScans: <n>/<required>`). Anything found resets the counter — fold it in
+through the normal pipeline and keep going.
+
+### F2 — Docs sync
+
+Update only the docs the change actually touched: `docs/WORKLOG.md` (always — one entry
+for the cycle), plus `docs/PROJECT.md` / `docs/CODE_MAP.md` / `docs/CHANGELOG.md` when the
+cycle changed architecture, surface area, or shipped behavior. Record: behavior
+implemented, API/schema/UI changes, migration steps, config changes, verification
+evidence, rollback notes.
+
+### F3 — Archive the cycle
 
-Finally set `Phase: done` in `docs/AI_HANDOFF/RUN.md`.
+When `handoff.fullstack.autoArchive` is true (default), archive per `handoff-clear`
+conventions so a future session needs no transcript to understand the cycle:
+
+1. Move the completed cycle's records (PLAN.md, SPEC.md, task files, ACTIVE.md snapshot)
+   into `docs/AI_HANDOFF/archive/cycle-<NN>/`.
+2. If `archive/` holds more than 3 cycle folders → fold the oldest into a one-line
+   summary in `HISTORY.md` and remove it.
+3. Reset `ACTIVE.md` to its empty template; clear `INDEX.md` rows to a fresh header;
+   remove `tasks/TASK-*.md`; clear `PLAN.md`/`SPEC.md` (templates stay).
+4. Commit the docs + archive changes:
+   `git add -A && git commit -m "handoff: finalize + archive cycle <ID>"`
+
+### F4 — Close the run
+
+Set `Phase: done` in `docs/AI_HANDOFF/RUN.md`, disarm any watchdog job armed at the
+start, and emit the Final Report below.
 
 ---
 
@@ -539,17 +680,40 @@ Re-run assertions after removal to confirm clean state.
 
 ## Final Report
 
+The ONLY legal first lines are:
+
+```
+HANDOFF FULLSTACK COMPLETE
+```
+or, when every remaining task shares one external blocker and no safe local work exists
+(RUN.md set to `Phase: blocked` first):
+```
+HANDOFF FULLSTACK BLOCKED
+```
+
+Then the body:
+
 ```
-handoff-fullstack complete:
   Cycle: <ID>
+  Spec: docs/AI_HANDOFF/SPEC.md
   Tasks: <N> approved, <M> blocked
+  Recovery/superseded: <TASK-xxx→TASK-xxx-R1, …> | none
+  Newly assigned processed: <n> | none
+  Quiet scans: <n>/<required>
   Fix rounds used: <0|1|2>
+  Verification: <commands + results>
   Git: <K> wave commits + pushed to <branch>
+  Docs updated: <files>
+  Archive: docs/AI_HANDOFF/archive/cycle-<NN>/
   Worktrees: all cleaned
   Branches: all cleaned
+  Remaining tasks: NONE | <list>
   Blocked (needs you): <TASK-xxx — one-line reason> | none
 ```
 
+A blocked report additionally lists: blocked tasks, exact blocker + evidence, attempted
+fixes, local work completed, and the recovery instructions for the next session.
+
 Then, as the last line of the run:
 
 > Cycle finished. Run `/compact` before starting the next cycle — this session is carrying

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

@@ -59,8 +59,12 @@ If this file already exists with `Phase:` not `done` when the command starts, th
 
 Read `docs/AI_HANDOFF/ACTIVE.md` → get `Base: <BASE>`.
 Read `docs/AI_HANDOFF/INDEX.md` → collect `ready` tasks (or the specific task named in the request above).
-If there are no `ready` tasks, check for `changes_requested`/`blocked` ones and run those
-instead. Only if nothing is actionable → report and stop.
+If there are no `ready` tasks, check for `changes_requested`/`blocked`/stale `in_progress`
+ones and run those instead. A stuck record that cannot resume (orphaned worktree,
+contradicting reports) gets the recovery treatment: mark it `cancelled_superseded`, create
+`TASK-xxx-R1` with the same spec references/acceptance/verification, and run the
+replacement — never leave stranded work just because a record was pending.
+Only if nothing is actionable → report and stop.
 
 Verify working tree state:
 ```bash
@@ -125,6 +129,9 @@ Each spawned agent works independently in its own worktree — **NO git commit,
 
 ```
 Read docs/AI_HANDOFF/tasks/TASK-xxx.md
+Read the SPEC.md sections named in the task's `Spec references` — the spec is the contract;
+the task file is the slice. If they disagree, implement the spec and note it in the task's
+## Discussion.
 
 TDD — mandatory:
   1. Write tests from §Test Cases

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

@@ -86,7 +86,10 @@ git status              # overview of modified/new/deleted files
 ```
 
 Review as one unified diff — correctness, regression risk, security, edge cases, maintainability.
-Cross-reference with each task's intent in `docs/AI_HANDOFF/tasks/TASK-xxx.md`.
+Cross-reference each task's intent in `docs/AI_HANDOFF/tasks/TASK-xxx.md` AND the
+`Spec references` sections it names in `docs/AI_HANDOFF/SPEC.md` — spec compliance is the
+primary correctness bar; a diff that drifts from the spec's contract fails even when it
+matches the task file's wording.
 
 ### 2d — Append verdict to each task file
 

package/templates/.claude/commands/ukit/handoff-status.md

@@ -12,8 +12,10 @@ Read and display current handoff state. Do NOT modify any files.
 
 1. `docs/AI_HANDOFF/ACTIVE.md` → cycle ID, goal, base branch
 2. `docs/AI_HANDOFF/INDEX.md` → all tasks + statuses
-3. `git worktree list` → open worktrees
-4. `git branch | grep handoff/` → open handoff branches
+3. `docs/AI_HANDOFF/RUN.md` → fullstack run cursor: `Phase:` ≠ `done`/`blocked` means a run is live and the Stop gate is holding the session to it
+4. `docs/AI_HANDOFF/SPEC.md` → spec exists/fresh (one line)
+5. `git worktree list` → open worktrees
+6. `git branch | grep handoff/` → open handoff branches
 
 ## Report
 
@@ -21,6 +23,8 @@ Read and display current handoff state. Do NOT modify any files.
 ━━━ Handoff Status ━━━━━━━━━━━━━━━━━━━━━━━━
 Cycle:  <ID>   Base: <branch>   Date: <date>
 Goal:   <goal>
+Run:    <Phase — or "no live cursor">
+Spec:   <present | missing>
 
 Tasks:
   ✅ done          TASK-001  <name>

package/templates/.claude/hooks/auto-allow-bash.sh

@@ -11,7 +11,15 @@ if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
 source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   trap ukit_cleanup_hook_input EXIT
   # Bounded stdin (H01): stage before anything reads it; the shell var is capped.
-  ukit_stage_hook_input 2097152 truncate || exit 0
+  ukit_stage_hook_input 2097152 truncate
+  __ukit_main_stage_rc=$?
+  if [ "$__ukit_main_stage_rc" -ne 0 ]; then
+    # Infra failure during staging (mktemp/truncate): payload was never
+    # inspected — announce the degrade (SPEC §8), never a silent pass.
+    ukit_emit_input_degraded advisory "auto-allow-bash"
+  fi
+# BUG-C21-01: a truncated/stalled staged payload must be announced (SPEC §8), never silently passed.
+ukit_input_degraded && ukit_emit_input_degraded advisory "auto-allow-bash"
 else
   # Runtime helper missing (pre-install tree): the SAME bounded staging,
   # inline - `cat >/dev/null` used to block forever on a producer that never
@@ -38,10 +46,14 @@ else
   wait "$__ukit_waiter" 2>/dev/null
   exec 8<&-
   __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
-  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
-  # already degrades on - the shared helper's truncate posture (R4.5).
-  if [ "$__ukit_size" -gt 2097152 ]; then
-    truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
+  if [ "$__ukit_stage_rc" -ne 0 ] || [ "$__ukit_size" -gt 2097152 ]; then
+    # BUG-C21-01 fallback parity (SPEC §8): a truncated/stalled staged payload
+    # must be announced, never silently acted on — same shape as the helper
+    # path's ukit_emit_input_degraded.
+    rm -f "$UKIT_INPUT_FILE"
+    UKIT_INPUT_FILE=""
+    printf '%s\n' '{"systemMessage":"UKit auto-allow-bash: tool-call payload was truncated or stalled during stdin staging; skipped this pass rather than act on incomplete input."}'
+    exit 0
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi

package/templates/.claude/hooks/block-dangerous.sh

@@ -11,7 +11,15 @@ if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
 source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   trap ukit_cleanup_hook_input EXIT
   # Bounded stdin (H01): stage before anything reads it; the shell var is capped.
-  ukit_stage_hook_input 2097152 truncate || exit 0
+  ukit_stage_hook_input 2097152 truncate
+  __ukit_main_stage_rc=$?
+  if [ "$__ukit_main_stage_rc" -ne 0 ]; then
+    # Infra failure during staging (mktemp/truncate): payload was never
+    # inspected — announce the degrade (SPEC §8), never a silent pass.
+    ukit_emit_input_degraded failclosed "dangerous-command gate"
+  fi
+# BUG-C21-01: a truncated/stalled staged payload must be announced (SPEC §8), never silently passed.
+ukit_input_degraded && ukit_emit_input_degraded failclosed "dangerous-command gate"
 else
   # Runtime helper missing (pre-install tree): the SAME bounded staging,
   # inline - `cat >/dev/null` used to block forever on a producer that never
@@ -38,10 +46,15 @@ else
   wait "$__ukit_waiter" 2>/dev/null
   exec 8<&-
   __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
-  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
-  # already degrades on - the shared helper's truncate posture (R4.5).
-  if [ "$__ukit_size" -gt 2097152 ]; then
-    truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
+  if [ "$__ukit_stage_rc" -ne 0 ] || [ "$__ukit_size" -gt 2097152 ]; then
+    # BUG-C21-01 fallback parity (SPEC §8): a truncated/stalled staged payload
+    # must be announced, never silently acted on — same shape as the helper
+    # path's ukit_emit_input_degraded.
+    rm -f "$UKIT_INPUT_FILE"
+    UKIT_INPUT_FILE=""
+    printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound), so dangerous-command gate cannot prove it safe. UKit defers this to a human decision."}}'
+    echo "BLOCKED: dangerous-command gate could not inspect a truncated/stalled payload; deferred to human." >&2
+    exit 2
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi

package/templates/.claude/hooks/completion-gate.sh

@@ -22,7 +22,15 @@ if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
 source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   trap ukit_cleanup_hook_input EXIT
   # Bounded stdin (H01): stage before anything reads it; the shell var is capped.
-  ukit_stage_hook_input 2097152 truncate || exit 0
+  ukit_stage_hook_input 2097152 truncate
+  __ukit_main_stage_rc=$?
+  if [ "$__ukit_main_stage_rc" -ne 0 ]; then
+    # Infra failure during staging (mktemp/truncate): payload was never
+    # inspected — announce the degrade (SPEC §8), never a silent pass.
+    ukit_emit_input_degraded advisory "stop gate"
+  fi
+# BUG-C21-01: a truncated/stalled staged payload must be announced (SPEC §8), never silently passed.
+ukit_input_degraded && ukit_emit_input_degraded advisory "stop gate"
 else
   # wrapper's own fail-loud behavior below alive.
   # Runtime helper missing (pre-install tree): the SAME bounded staging,
@@ -50,10 +58,14 @@ else
   wait "$__ukit_waiter" 2>/dev/null
   exec 8<&-
   __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
-  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
-  # already degrades on - the shared helper's truncate posture (R4.5).
-  if [ "$__ukit_size" -gt 2097152 ]; then
-    truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
+  if [ "$__ukit_stage_rc" -ne 0 ] || [ "$__ukit_size" -gt 2097152 ]; then
+    # BUG-C21-01 fallback parity (SPEC §8): a truncated/stalled staged payload
+    # must be announced, never silently acted on — same shape as the helper
+    # path's ukit_emit_input_degraded.
+    rm -f "$UKIT_INPUT_FILE"
+    UKIT_INPUT_FILE=""
+    printf '%s\n' '{"systemMessage":"UKit stop gate: tool-call payload was truncated or stalled during stdin staging; skipped this pass rather than act on incomplete input."}'
+    exit 0
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi

package/templates/.claude/hooks/compress-output.sh

@@ -18,7 +18,15 @@ if [ -f "$SCRIPT_PATH" ]; then
     trap ukit_cleanup_hook_input EXIT
     # Bounded stdin (H01): compressed tool output can be large, so the staged
     # file is the transport and the shell var only mirrors the capped payload.
-    ukit_stage_hook_input 33554432 temp-file || exit 0
+    ukit_stage_hook_input 33554432 temp-file
+    __ukit_main_stage_rc=$?
+    if [ "$__ukit_main_stage_rc" -ne 0 ]; then
+      # Infra failure during staging (mktemp/truncate): payload was never
+      # inspected — announce the degrade (SPEC §8), never a silent pass.
+      ukit_emit_input_degraded advisory "output compression"
+    fi
+    # BUG-C21-01: a truncated/stalled staged payload must be announced (SPEC §8), never silently passed.
+    ukit_input_degraded && ukit_emit_input_degraded advisory "output compression"
   else
       # Runtime helper missing (pre-install tree): the SAME bounded staging,
   # inline — `cat >/dev/null` used to block forever on a producer that never
@@ -45,14 +53,15 @@ if [ -f "$SCRIPT_PATH" ]; then
   wait "$__ukit_waiter" 2>/dev/null
   exec 8<&-
   __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
-  if [ "$__ukit_stage_rc" -ne 0 ]; then
-    # Unstaged: the hook cannot inspect this payload.
+  if [ "$__ukit_stage_rc" -ne 0 ] || [ "$__ukit_size" -gt 33554432 ]; then
+    # Unstaged or oversized: the hook cannot inspect this payload — announce
+    # the degrade (SPEC §8) instead of silently compressing an empty or
+    # truncated input (SUS-02 / BUG-C21-01 fallback parity).
     rm -f "$UKIT_INPUT_FILE"
     UKIT_INPUT_FILE=""
+    printf '%s\n' '{"systemMessage":"UKit output compression: tool-call payload was truncated or stalled during stdin staging; skipped this pass rather than act on incomplete input."}'
+    exit 0
   else
-    if [ "$__ukit_size" -gt 33554432 ]; then
-      truncate -s 33554432 "$UKIT_INPUT_FILE" 2>/dev/null
-    fi
     trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
   fi
   fi