@ngockhoale/ukit 2.0.7 → 2.1.2

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to UKit are documented here.
 
+## 2.1.2 - 2026-08-16
+
+Follow-up to 2.1.0, which fixed the wrong hook. Runs were still freezing mid-task because the gate that actually blocks tools was never touched.
+
+### Fixed
+
+- **`context-hardcap-gate.sh` gets a grace window for unfinished runs.** 2.1.0 made the *advisory* `context-window-guard.sh` (UserPromptSubmit) run-cursor aware, but the halt users hit came from `context-hardcap-gate.sh` — a separate PreToolUse hook that hard-refuses Edit/Write/Bash with `exit 2` once `estimatedTotalTokens >= compact.hardCapTokens`. It knew nothing about `docs/AI_HANDOFF/RUN.md`, so it froze runs mid-edit exactly as before 2.1.0. It now reads the run cursor and, while a run is unfinished, allows a bounded `compact.hardCapGraceCalls` (default 10) further calls with an explicit "spend this on landing, not new work" directive — finish the edit, commit, write the cursor, push — then blocks hard as it always did.
+
+### Added
+
+- **`compact.hardCapGraceCalls`** (default `10`). Budget is per over-cap episode, not per wave: it resets only when the token estimate actually falls (a real compaction happened), so a long run cannot mint itself unlimited grace by advancing its cursor. With no unfinished run the gate's behavior is unchanged.
+- **`tests/hooks/contextHardcapGate.test.js`** — 12 cases covering under-cap pass-through, blocking with no run in flight, `Phase: done` treated as no run, grace grant/exhaustion, no top-up on cursor advance, budget restored after a real compaction, `hardCapBlock=false` escape hatch, non-gated tools, fail-open on malformed input, template/mirror parity, and manifest+settings wiring.
+
+### Notes
+
+- **No hook can call `/compact`** — it is a client-only command, so UKit cannot auto-compact on your behalf. The supported path is: land inside the grace window → user runs `/compact` (or Claude Code's own auto-compact fires) → the `handoff-resume.sh` SessionStart hook replays the cursor → the run continues. Enabling auto-compact in Claude Code's `/config` makes that middle step automatic.
+
+## 2.1.0 - 2026-08-16
+
+Handoff autonomy wave: `/ukit:handoff-fullstack` runs a whole goal end-to-end without stopping to ask. Questions are collected once, up front, in the planning phase; everything that used to be a mid-run STOP now resolves automatically and keeps going.
+
+### Added
+
+- **Autonomy Contract in all four handoff commands.** `handoff-create` owns the single question window — one batched `AskUserQuestion` (max 4, recommended option first) before planning starts, covering scope, conflicting interpretations, subsystem choice and acceptance criteria only. `handoff-fullstack`, `handoff-implement` and `handoff-review` ask nothing between that window and the Final Report; each command carries a table mapping every former STOP to its required automatic behavior.
+- **Run cursor + resume protocol (`docs/AI_HANDOFF/RUN.md`).** Every phase transition writes `Phase`/`Cursor`/`Next`. A `Phase:` other than `done` means the next session is a continuation: no re-plan, no re-scope, no questions. New config `handoff.autonomy.resumeFromCursor` / `runCursorFile`.
+- **`handoff-resume.sh` SessionStart hook** (manifest id `hook-handoff-resume`). Reads the run cursor and prints a resume banner with Goal/Base/Phase/Cursor/Next, plus two extra lines when the session started from `source: compact`. Advisory only, always exits 0, silent when there is no unfinished run.
+- **Auto-fix loop after review (max 2 rounds).** Non-approved tasks are re-waved and re-implemented in parallel — agents read their own `## Reviewer Verdict` from disk — then committed and re-reviewed. After round 2 the stuck tasks stay `blocked` and the rest of the pipeline proceeds instead of halting. Config: `handoff.autonomy.autoFixRounds`.
+- **Planner Grounding + 12-point Self-Audit.** `handoff-planner` must verify that every Target File exists (or is marked `(new)`), that every Verification Command is a real `package.json` script, and that test file paths match the neighbouring test layout; then run a 12-point self-audit (coverage / correctness / test quality, including "could every listed test pass against an empty implementation?") and report the result. Compensates for dropping plan review from 3 rounds to 2.
+- **Wave-boundary commit + context checkpoint.** Each wave ends with `git add -A && git commit -m "handoff: wave <N> — TASK-00x, ..."`, a cursor update, and a collapse of that wave to one line per task in working memory. Config: `handoff.autonomy.commitPerWave`.
+
+### Changed
+
+- **`git push` moved from the `ask` list to `allow`** in default settings, alongside `git add`, `git commit` and `git worktree`. Runs no longer stop at the final step for a confirmation. `git push --force` and `--force-with-lease` remain in `deny`, which still wins over `allow`.
+- **Subagent return contracts are now capped.** Executors return ≤10 lines (`TASK`/`STATUS`/`EXECUTOR_MODEL`/`FILES`/`RED`/`VERIFY`/`NOTE`), reviewers ≤6. Verbose agent reports injected back into the orchestrator were the main cause of context exhaustion on long fullstack runs; this addresses it structurally rather than by raising caps.
+- **`context-window-guard.sh` is now run-cursor aware.** With an unfinished run it emits shed-context-and-continue instructions instead of the stop-and-`/compact` directive. Asking the user to `/compact` is permitted only at a cycle boundary, in the Final Report — never mid-task. Config: `handoff.autonomy.compactAtCycleBoundaryOnly`.
+- **Same-wave file conflicts auto-serialize** instead of marking both tasks `needs_breakdown`: the higher-numbered task gains a `Dependencies: TASK-<lower>` line and moves to the next wave. Config: `handoff.autonomy.autoSerializeFileConflicts`.
+- **A dirty working tree no longer blocks Phase 3.** It is committed as `handoff: checkpoint before implement` and the run continues.
+- **Plan review loop cap: 3 rounds → 2**, then findings are applied and the run proceeds (logged as `### Round <N> — findings applied without re-review`). Config: `handoff.autonomy.planReviewRounds`.
+- **Review diff range is now anchored to the plan commit** (`git log --grep='^handoff: plan' -n 1`) rather than the working tree, since waves are committed as they finish.
+- **`handoff-planner` maximizes wave width.** `Dependencies: none` unless task B genuinely cannot be written without A's output — ordering preference, same code area and review order are explicitly not dependencies.
+- **`feature-implementer` and `code-reviewer` run unattended in handoff mode.** Ambiguity resolves through task file → PLAN.md → surrounding code → recommended choice, recorded in `## Discussion`; reviewer findings must be actionable defects (`file:line` + concrete failure + what correct looks like), never questions. Daily (non-handoff) behavior is unchanged.
+- **`handoff-model-guard.sh` gained a bash fast path** that skips the node spawn when the payload contains neither `AI_HANDOFF` nor `git push`. Behavior-identical (verified against the previous version across a 6-payload sweep); measured 67ms → 38ms per ordinary Bash/Edit/Write call, paid on every call in every parallel subagent.
+
 ## 2.0.7 - 2026-08-15
 
 ### Added

package/manifests/platform.full.yaml

@@ -1121,6 +1121,17 @@ items:
     packs:
       - core
 
+  - id: hook-handoff-resume
+    type: hook
+    sourceTemplate: .claude/hooks/handoff-resume.sh
+    targetPath: .claude/hooks/handoff-resume.sh
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-reset-compact-pressure
     type: hook
     sourceTemplate: .claude/hooks/reset-compact-pressure.sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.0.7",
+  "version": "2.1.2",
   "description": "Install/update an index-first AI workspace for Claude Code, Antigravity, OpenAI Codex, and OpenCode.",
   "license": "MIT",
   "type": "module",

package/templates/.claude/agents/code-reviewer.md

@@ -67,6 +67,27 @@ NOTES: [1-2 sentences for human reviewer if needed]
 
 After writing the verdict, update `docs/AI_HANDOFF/INDEX.md` row for this task: set Status = NEXT_STATUS_FOR_INDEX, set Reviewer = your model name.
 
+**Then return to the orchestrator at most 6 lines** — the full verdict is already on disk:
+
+```
+TASK: TASK-xxx
+VERDICT: approved | approved_minor | changes_requested | critical_block
+REVIEWER_MODEL: <exact model ID>
+VERIFICATION_RERUN: PASS | FAIL
+BLOCKING: <one line per critical/important finding, or "none">
+```
+
+Do not paste the diff, the findings prose, or verification output into the returned message.
+The orchestrator is driving a whole pipeline in one context window and re-reads what it needs
+from the task file; pasted reviewer logs are a common reason a run exhausts its context and
+dies before the cycle finishes.
+
+**You may be running unattended.** Findings do not end the run — the caller feeds them to an
+auto-fix round and re-review. So write findings that a fresh executor can act on with no human
+present: point at `file:line`, state the concrete failure, and say what correct looks like. A
+finding phrased as a question ("should this handle null?") is not actionable; phrase it as the
+defect ("`parse()` at foo.js:41 throws on null input; expected an empty result").
+
 ### Model isolation check (FIRST thing you do)
 
 UKit cannot force any tool to use a specific model. The contract is enforced HERE, by you, via self-report comparison.

package/templates/.claude/agents/feature-implementer.md

@@ -12,7 +12,15 @@ Implement requested behavior with minimal scope drift.
 - **Daily/ad-hoc mode** (DEFAULT): task didn't come from `docs/AI_HANDOFF/` → use the original lightweight workflow. Tests only when touched code already has coverage. No reviewer trigger.
 - **Handoff mode**: task file is `docs/AI_HANDOFF/tasks/TASK-xxx.md` OR user explicitly invokes handoff (e.g. "execute task TASK-001") → activate full Quality Gate: test-first → green → reviewer.
 
-If unsure, ask the user. Don't apply Handoff mode rules to a quick one-off fix.
+If unsure which mode applies, ask the user. Don't apply Handoff mode rules to a quick one-off fix.
+
+**In Handoff mode you are running unattended — ask nothing.** You were spawned by an
+orchestrator driving a pipeline; there is no human in your conversation to answer, and a
+question there is silently dropped while the run stalls. Resolve ambiguity in this order:
+the task file → `PLAN.md` → the surrounding code's existing patterns → the choice you would
+recommend. Record what you chose and why in the task's `## Discussion` thread. Only a blocker
+outside the repo (missing credential, unreachable service) justifies reporting `FAIL` early —
+and even then, report it, don't ask about it.
 
 ## Workflow
 
@@ -25,7 +33,7 @@ If unsure, ask the user. Don't apply Handoff mode rules to a quick one-off fix.
   - non-trivial: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`
 - Identify target files and existing patterns.
 - If task came from handoff, read `tasks/TASK-xxx.md` and locate its **Test Plan** + **Verification Commands**.
-- If confidence is low or risk is high, ask one short clarifying question before deeper analysis.
+- Daily mode: if confidence is low or risk is high, ask one short clarifying question before deeper analysis. Handoff mode: do not ask — decide and record the decision (see above).
 
 ### 2. Plan Approach (< 1 minute)
 
@@ -79,6 +87,26 @@ NEXT: [follow-up needed, or "ready for review"]
 
 > **Self-report rule:** UKit cannot force any tool/host to use a specific model. Your self-reported `EXECUTOR_MODEL` is how the reviewer (in another tool or subagent) knows what to compare against its own model. Misreporting → reviewer refuses and asks the human to confirm.
 
+**Handoff mode — where that report goes.** Append the block above, in full, to the task file
+as `## Executor Report` (or `## Executor Report (fix round <N>)` on a re-run). Then return to
+the orchestrator **at most 10 lines**:
+
+```
+TASK: TASK-xxx
+STATUS: PASS | FAIL
+EXECUTOR_MODEL: <exact model ID>
+FILES: <comma-separated changed paths>
+RED: confirmed | not-confirmed
+VERIFY: <n> commands, all pass | <first failing command + one-line reason>
+NOTE: <one line, or "none">
+```
+
+Do not repeat RED output, verification logs, diffs, or file contents in the returned message.
+The reviewer reads all of that from the task file on disk. The orchestrator is driving a whole
+pipeline in one context window, and pasted subagent logs are the single biggest reason a run
+runs out of context and dies half-finished. Being terse here is not a style preference — it is
+what lets the cycle reach the end.
+
 ### 7. Trigger Reviewer — Handoff mode ONLY
 
 - Daily mode: skip this step entirely. Just report and stop.

package/templates/.claude/agents/handoff-planner.md

@@ -17,15 +17,43 @@ Use the strongest model available — planning with a weak model produces weak t
 
 ## Scope Check (before Phase 1)
 
-Before refining the request into `PLAN.md`, check whether it describes multiple independent subsystems (e.g. "CRM + AI + billing + analytics + mobile app"). If yes, stop and output a decomposition table instead of planning the mega-spec:
+Before refining the request into `PLAN.md`, check whether it describes multiple independent subsystems (e.g. "CRM + AI + billing + analytics + mobile app"). If yes, record the decomposition:
 
 ```
 Scope complexity: HIGH
 Detected systems: [...]
-Recommended decomposition: N modules — plan each as a separate PLAN.md
+Decomposition: N modules — module 1 planned now, modules 2..N queued
 ```
 
-Wait for human confirmation before writing `PLAN.md`.
+Then **plan module 1 in full and keep going** — do not wait for confirmation. A mega-spec is
+what you must avoid, not the work itself. Write the remaining modules into `PLAN.md` §2 as
+explicitly out-of-scope-for-this-cycle, and add one `queued` row per module to `INDEX.md` so
+the next cycle picks them up. Order modules so the one others depend on is planned first.
+
+The caller may be running unattended (`/ukit:handoff-fullstack`). Stopping to ask means the
+run dies and the human returns hours later to a question, which is the failure mode this
+whole pipeline exists to prevent.
+
+## Grounding — every path and command must be real
+
+The most common way a plan fails is not bad reasoning, it is **confident invention**: a target
+file that doesn't exist, a test command the project doesn't have, an import path that never
+resolved. Executors then burn a whole round discovering it.
+
+Before writing any path or command into `PLAN.md` or a task file, verify it:
+
+- **Target Files** — for each path, confirm it exists (`ls`/Glob), or that its parent
+  directory exists and the file is genuinely new. Mark new files `(new)` explicitly.
+- **Verification Commands** — read `package.json` `scripts` (or the stack's equivalent) and
+  use the script names that are actually defined. Do not write `npm test` when the repo uses
+  `yarn test`, and do not invent a `lint` script that isn't there. Run `--help` or a dry check
+  if unsure.
+- **Test Files** — follow the existing test layout and naming; open one neighbouring test file
+  and match its structure, framework and import style.
+- **Interfaces** — quote real signatures from the source, not plausible-looking ones.
+
+If something cannot be verified, say so in the task's `## Discussion` rather than guessing.
+A stated unknown costs the executor one read; a wrong path costs it a round.
 
 ## Phase 1 — Write PLAN.md
 
@@ -88,6 +116,30 @@ Missing any field → `needs_breakdown`. Never mark incomplete tasks `ready`.
 - Chain: A → B → C runs as 3 sequential waves (1 task each, no parallelism)
 - Independent: A, B, C (all `none`) runs as 1 wave, all parallel
 
+### Maximize wave width — dependencies are expensive
+
+Wave width is the single biggest lever on how long a cycle takes: a wave of 6 finishes in
+roughly the time of its slowest task, while a chain of 6 takes six times that. Executors run
+up to `handoff.maxParallelAgents` (default 10) at once, so a plan that produces `none`
+dependencies for most tasks is dramatically faster than one that produces a chain.
+
+**Write `Dependencies: none` unless B genuinely cannot be written without A's output.** A real
+dependency means B imports a symbol A creates, or B tests behavior A implements. These are
+*not* dependencies:
+
+- "B is logically later" or "B builds on the same feature" — ordering preference, not a
+  dependency.
+- "Both touch the same area of the codebase" — irrelevant unless they touch the same *file*.
+- "A should be reviewed before B starts" — that is what the review phase is for.
+
+Same-file collisions are the one real constraint, and they are cheap to design around: split
+along file boundaries so each task owns its files outright. If two pieces of work truly must
+edit one file, prefer merging them into a single task over chaining two — one task with two
+test groups beats two waves.
+
+Before finalizing, count your waves. If the dependency graph is mostly a chain, re-examine it:
+most chains are ordering preferences that a wide wave 1 would satisfy just as well.
+
 ## Phase 3 — Update state files
 
 **INDEX.md** row per task: `| TASK-001 | <name> | ready | none | - |`
@@ -101,15 +153,59 @@ Status: planning_done — ready for executor
 ```
 Wave structure is NOT stored here — inferred from task `Dependencies` fields at runtime.
 
+## Self-Audit — run before reporting, every time
+
+The downstream pipeline is unattended: an incomplete or wrong plan is not caught by a human
+skimming it, it is caught by an executor failing three hours later. Independent plan review
+runs at most twice, so this audit is your own last line of defense.
+
+Walk the checklist and **fix what fails before you report** — do not report and hope review
+catches it:
+
+**Coverage — is anything missing?**
+1. Does every acceptance criterion in §6 trace to at least one task? Name the task per criterion.
+2. Does every task trace back to something in §1/§6? A task nothing asks for is scope creep — cut it.
+3. Do the tasks together actually deliver §1's success definition, or only the easy part of it? State the gap if there is one.
+4. Is the *unhappy* path planned — errors, empty input, permissions, migration of existing data — or only the feature?
+
+**Correctness — is anything wrong?**
+5. Every `Target Files` path verified per Grounding? Any `(new)` file marked as such?
+6. Every `Verification Command` a real, defined script in this repo?
+7. Any two same-wave tasks sharing a file? If yes, merge them or add the dependency now — the executor will otherwise serialize them for you and your wave plan was a lie.
+8. Does any task depend on a symbol or file that no earlier task creates? That's a missing task, not a dependency.
+
+**Test quality — the part most often faked:**
+9. Each task: ≥1 happy path + ≥2 edge cases of genuinely *different kinds*. "empty string" and "null" are the same kind — boundary, concurrency, malformed input, permission denied, duplicate, ordering are different kinds.
+10. Does each test case state a concrete `Expected` value, not "works correctly" or "returns successfully"? A test whose expectation cannot fail is not a test.
+11. Bugfix task → is there a regression test that fails against today's code?
+12. Could every listed test pass against an empty implementation? If so, the test cases describe nothing and must be rewritten.
+
+Append the result to `PLAN.md`:
+```
+## Planner Self-Audit
+Checklist: 12/12 pass
+Fixed during audit: <what you changed, or "nothing">
+Known gaps: <what you deliberately left out and why, or "none">
+```
+
+An honest `Known gaps` line is worth more than a clean sheet — it is the one thing the reviewer
+and executor cannot recover on their own.
+
 ## Output
 
+Keep the returned message under 25 lines — the caller may be an orchestrator whose context
+budget is the constraint on the whole run. Detail belongs in `PLAN.md`, not in the reply.
+
 - Task count + IDs
 - Dependency graph (text form: TASK-001 → TASK-003, TASK-002 independent)
+- Wave plan: `wave 1: N tasks | wave 2: M tasks` — flag it if the graph is mostly a chain
+- Self-audit result + any `Known gaps`
 - Any `needs_breakdown` tasks + reason
 - Next step: "Switch to Sonnet/unic-code → run `/ukit:handoff-implement`"
 
 ## Rules
 
 - Do NOT implement. Job ends when all tasks are `ready` or `needs_breakdown`.
-- Undone tasks in INDEX.md → warn human: continue old cycle or start fresh?
-- Cannot determine test cases → `needs_breakdown` + Discussion thread note.
+- Undone tasks in INDEX.md → continue that cycle; plan only what is still missing. Do not ask whether to start fresh, and do not overwrite task files that already carry an executor report or reviewer verdict.
+- Cannot determine test cases → `needs_breakdown` + Discussion thread note. Never mark a task `ready` with vague tests just to keep the pipeline moving — a task with fake tests passes review and ships a bug, which costs far more than one blocked task.
+- You may be invoked unattended. Ask nothing; where the caller allowed questions, that window closed before you were spawned. Resolve ambiguity by reading the codebase, choose the option you would recommend, and record the choice and its rationale in `PLAN.md §3`.

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

@@ -14,6 +14,29 @@ $ARGUMENTS
 
 ---
 
+## Question Policy — this is the one phase that may ask
+
+Planning is the **only** place in the handoff pipeline where asking the human is allowed, and
+it is where every ambiguity must be burned off. Whatever is left unresolved here becomes a
+guess during implementation, where nobody is available to correct it.
+
+**Ask once, up front, batched.** Before Step 1, if `$ARGUMENTS` leaves a choice that changes
+*what gets built* — not how — collect every such question into a **single** `AskUserQuestion`
+call (max 4 questions, each with a `(Recommended)` first option). Then close the window.
+
+Ask about: ambiguous scope boundaries, conflicting interpretations of the request, which
+existing subsystem to extend versus replace, and any acceptance criterion you would otherwise
+invent. Do **not** ask about: file layout, naming, test framework choice, library versions
+already used in the repo, or anything the codebase or `docs/` already answers — resolve those
+by reading, and record the resolution in `PLAN.md §3`.
+
+Record every answer verbatim in `PLAN.md §1 Intent`. Downstream phases treat that section as
+the human's own words and never re-ask.
+
+After the batched call, run Steps 1–2.5 to completion without further questions.
+
+---
+
 ## Step 1 — Read context (lite model)
 
 **Claude Code — MANDATORY, do this before anything else:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"`. Do NOT read these files yourself in the current session — this step is contracted to the lite tier (haiku/unic-lite), which only the spawned agent's frontmatter model guarantees. Ask the agent to:
@@ -36,7 +59,7 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
 
 1. Check INDEX.md task statuses:
    - All tasks are `ready` (planning only) → **re-run allowed**: overwrite PLAN.md and TASK-xxx.md freely — this is iterative refinement.
-   - Any task is `pending_review`, `changes_requested`, `merge_conflict`, or `blocked` → **STOP**: warn human — tasks are already in implement/review phase, cannot overwrite safely.
+   - Any task is `pending_review`, `changes_requested`, `merge_conflict`, or `blocked` → **do not overwrite**: that cycle is mid-flight and its task files carry executor reports and verdicts. Report which tasks are in flight and point the human at `/ukit:handoff-review` (to finish the cycle) or `/ukit:handoff-clear` (to abandon it). Planning is the one phase where stopping is correct — there is nothing safe to do automatically here.
    - No tasks → fresh cycle, proceed normally.
 
 2. Resolve base branch:
@@ -87,7 +110,14 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
 
 ## Step 2.5 — Independent plan review (strong model, separate agent)
 
-**Loop cap — check first:** count `### Round` entries in PLAN.md's `## Plan Review Log` (0 if the section doesn't exist yet). If count ≥ 3 (3 prior rounds already returned `Issues Found`), do NOT invoke the reviewer again — STOP and escalate to the human: show the accumulated findings from all 3 rounds, ask them to manually revise PLAN.md, narrow scope, or explicitly approve an override. Otherwise, proceed below.
+**Loop cap — check first:** count `### Round` entries in PLAN.md's `## Plan Review Log` (0 if the section doesn't exist yet).
+
+- count = 0 → run the review below.
+- count = 1 and the round returned `Issues Found` → planner revises once, then run **one** more review round.
+- count ≥ 2 → do NOT invoke the reviewer again, and do not stop. Have the planner apply every outstanding finding directly to `PLAN.md` and the affected `TASK-xxx.md` files, append `### Round <N> — findings applied without re-review` listing what changed, then finish.
+
+Two independent strong-model passes shape the plan before any code is written — that gate is
+intact. What it no longer does is hand a stalled plan back and wait.
 
 **Claude Code — MANDATORY, do this before anything else:** call the Agent tool with `subagent_type: "code-reviewer"`, passing `REVIEW_TARGET_TYPE=plan` and the path to `docs/AI_HANDOFF/PLAN.md`. This MUST be a separate agent invocation from Step 2's `handoff-planner` call (fresh context) — same-session self-review defeats the purpose of an independent gate.