@ngockhoale/ukit 2.1.4 → 2.1.5

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to UKit are documented here.
 
+## 2.1.5 - 2026-08-19
+
+`local-build` was the one execution contract in the daily (non-handoff) flow that let the executor claim done off write evidence alone — and it is also the busiest lane a weaker `unic-code` backend hits. This closes that gap and adds a non-blocking second opinion, without adding wait time to the main task.
+
+### Changed
+
+- **`local-build` now requires verification evidence, not just write evidence, before claiming done.** `orchestration.contracts['local-build'].completionRule` was `require-write`; every other multi-step contract (`shared-edit`, `find-cause`, `map-impact`) already required verification too, so `local-build` was the odd one out — the exact lane where a weaker executor model producing "silly bugs" that pass a glance but fail a real check would go unnoticed. `completionEvidence` now includes `verification-evidence` alongside `write-evidence` in `src/index/taskRouting.js`, mirrored in `src/core/runtimeConfig.js` and both `config.json` copies. `tests/index/taskRouting.test.js` and `tests/core/runtimeConfig.test.js` lock the new requirement.
+
+### Added
+
+- **Non-blocking sidecar diff review for `local-build` and `shared-edit`.** After write + verification evidence exist for one of these tasks, routed state now carries a `review=code-reviewer(diff)` segment (`routeSummary.postEditReview`) instructing the agent to launch `code-reviewer` in the background (`run_in_background: true`, `REVIEW_TARGET_TYPE=diff`, model `unic-smart` per the new `subagents.diffReviewModel`) — reusing the reviewer-model-differs-from-executor precedent from `handoff.reviewer`, since a background pass can afford a stronger model without slowing the main task down. Findings are advisory only; the main task's completion is never blocked or reopened on their account. New `code-reviewer.md` mode: `REVIEW_TARGET_TYPE=diff`, documented in `templates/.claude/agents/code-reviewer.md` (mirrored byte-identically to `.claude/agents/code-reviewer.md`) and wired into `templates/CLAUDE.md` / this repo's own `CLAUDE.md` under "Post-Edit Sidecar Review (internal)".
+- **`subagents.diffReviewEnabled` / `diffReviewAgent` / `diffReviewModel`** — new config fields in both `.ukit/storage/config.json` and `templates/ukit/storage/config.json`, defaulting to `true` / `code-reviewer` / `unic-smart`.
+
 ## 2.1.4 - 2026-08-19
 
 More room before compaction, the handoff hooks stop taxing every call they were meant to speed up, and the shipped handoff instructions stop contradicting the config they tell agents to read.

package/package.json

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

package/src/core/runtimeConfig.js

@@ -145,8 +145,9 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
           maxReadPasses: 2,
           maxContextPulls: 1,
           verificationPolicy: 'targeted-if-covered',
-          completionRule: 'require-write',
+          completionRule: 'require-write-and-verification',
           delegationPolicy: 'disallow-by-default',
+          postEditReviewPolicy: 'sidecar-non-blocking',
         },
         'find-cause': {
           maxReadPassesBeforeReassess: 3,
@@ -160,6 +161,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
           verificationPolicy: 'targeted-then-widen-on-risk',
           completionRule: 'require-write-and-verification',
           delegationPolicy: 'allow-qualified-sidecar',
+          postEditReviewPolicy: 'sidecar-non-blocking',
         },
         'map-impact': {
           maxReadPasses: 3,
@@ -224,6 +226,9 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       enabled: true,
       smallTaskModel: 'unic-lite',
       smallTaskAgent: 'ukit-small-task-maintainer',
+      diffReviewEnabled: true,
+      diffReviewAgent: 'code-reviewer',
+      diffReviewModel: 'unic-smart',
       visionEnabled: true,
       visionModel: 'unic-vision',
       visionAgent: 'ukit-vision-analyst',

package/src/index/taskRouting.js

@@ -235,6 +235,9 @@ export function buildRouteSummary({
     executionCandidates,
   });
   const executionContract = buildExecutionContract(executionMode);
+  const postEditReview = executionContract?.postEditReviewPolicy
+    ? { policy: executionContract.postEditReviewPolicy, agent: 'code-reviewer', reviewTargetType: 'diff' }
+    : null;
   const completionState = buildCompletionState({
     executionMode,
     verificationRecommendation,
@@ -263,6 +266,7 @@ export function buildRouteSummary({
     editGuardHint ? `editGuard=${editGuardHint}` : null,
     delegationRecommendation?.hint ? `delegate=${delegationRecommendation.hint}` : null,
     policyMode ? `policy=${policyMode}` : null,
+    postEditReview ? `review=${postEditReview.agent}(${postEditReview.reviewTargetType})` : null,
     handoffBudget?.warning ? `budget=${handoffBudget.warning}` : null,
     worklogBudget?.warning ? `budget=${worklogBudget.warning}` : null,
   ].filter(Boolean).join(' | ');
@@ -279,6 +283,7 @@ export function buildRouteSummary({
     approachSelector,
     executionContract,
     completionState,
+    postEditReview,
     continuationState,
     intentMode: routingContext.intentMode ?? null,
     handoffFile,
@@ -580,9 +585,10 @@ function buildExecutionContract(executionMode = null) {
       maxReadPasses: 2,
       maxContextPulls: 1,
       verificationPolicy: 'targeted-if-covered',
-      completionRule: 'require-write',
+      completionRule: 'require-write-and-verification',
       delegationPolicy: 'disallow-by-default',
-      completionEvidence: ['write-evidence'],
+      completionEvidence: ['write-evidence', 'verification-evidence'],
+      postEditReviewPolicy: 'sidecar-non-blocking',
     },
     'find-cause': {
       maxReadPassesBeforeReassess: 3,
@@ -599,6 +605,7 @@ function buildExecutionContract(executionMode = null) {
       delegationPolicy: 'allow-qualified-sidecar',
       completionEvidence: ['write-evidence', 'verification-evidence'],
       mirrorConsistencyRequired: true,
+      postEditReviewPolicy: 'sidecar-non-blocking',
     },
     'map-impact': {
       maxReadPasses: 3,

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

@@ -1,6 +1,6 @@
 ---
 name: code-reviewer
-description: "Independent reviewer for handoff Phase 3, and for spec/plan documents. For code (default): use after executor reports STATUS: DONE on a handoff task, MUST run with a model different from the executor (configured in .ukit/storage/config.json → handoff.reviewer.model, default unic-smart), produces a verdict: APPROVED | APPROVED-WITH-MINOR | CHANGES-REQUESTED | CRITICAL. For spec/plan documents (set REVIEW_TARGET_TYPE=spec or plan): reviews a docs/plans/*.md file for completeness/consistency/clarity/scope/YAGNI, produces Status: Approved | Issues Found."
+description: "Independent reviewer for handoff Phase 3, for spec/plan documents, and for non-blocking sidecar diff review of daily-flow edits. For code (default): use after executor reports STATUS: DONE on a handoff task, MUST run with a model different from the executor (configured in .ukit/storage/config.json → handoff.reviewer.model, default unic-smart), produces a verdict: APPROVED | APPROVED-WITH-MINOR | CHANGES-REQUESTED | CRITICAL. For spec/plan documents (set REVIEW_TARGET_TYPE=spec or plan): reviews a docs/plans/*.md file for completeness/consistency/clarity/scope/YAGNI, produces Status: Approved | Issues Found. For sidecar diff review (set REVIEW_TARGET_TYPE=diff): reviews the current uncommitted git diff after a local-build/shared-edit task, runs in the background and never blocks the main task, produces STATUS: clean | issues-found."
 model: opus  # unic-smart
 color: yellow
 tools: ["Read", "Grep", "Glob", "Bash"]
@@ -14,6 +14,7 @@ You are the independent reviewer for UKit's handoff Quality Gate. Your model is
 
 - `code` (default, if not specified) — reviewing a handoff task diff. Follow **Code Review** below, unchanged.
 - `spec` | `plan` — reviewing a document (e.g. `docs/plans/*.md`), no diff/task file/executor report involved. Skip straight to **Spec/Plan Review** at the end of this file instead.
+- `diff` — non-blocking sidecar review of the current uncommitted diff in the daily (non-handoff) flow. No task file/executor report/model-isolation check involved. Skip straight to **Sidecar Diff Review** at the end of this file instead.
 
 ## Code Review (REVIEW_TARGET_TYPE=code)
 
@@ -155,3 +156,43 @@ NOTES: [1-2 sentences if needed]
 ```
 
 `<N>` = 1 + however many `### Round` entries already exist in the log (1 if this is the first review).
+
+## Sidecar Diff Review (REVIEW_TARGET_TYPE=diff)
+
+This mode exists so a weaker daily-flow executor model still gets a second pair of eyes,
+without adding wait time to the main task. You are launched in the background right after
+the main task already has write + verification evidence; the caller is not waiting on you.
+
+### Inputs you expect
+
+- No task file, no executor report, no model-isolation check. Just read the current uncommitted
+  diff yourself: `git diff` (and `git diff --stat` for an overview). If there is no diff, report
+  `STATUS: clean` with `FINDINGS: none` and stop.
+
+### Review order
+
+Apply the same lenses as Code Review's steps 2-6, scoped to what the diff actually touches:
+
+1. **Correctness** — Does the diff do what it looks like it's trying to do? Wrong assumptions, stale refs, missing cases?
+2. **Regression risk** — Any existing behavior/tests/contracts this plausibly breaks?
+3. **Safety / security / data loss** — Destructive actions, auth/permission, path handling, unsafe shell/DB/file ops.
+4. **Performance / scale** — Accidental N+1, repeated I/O, large scans in hot paths.
+5. **Maintainability** — Duplicated logic, dead branches, misleading naming, drift between docs/tests/source.
+
+Do not re-run the project's full verification suite here — this is an advisory pass, not a gate.
+You may read files for context but this mode never edits anything.
+
+### Output
+
+Keep it short — this is a quick advisory pass, not a full verdict:
+
+```
+STATUS: clean | issues-found
+FINDINGS:
+  - file:line — what's wrong, why it matters
+NOTES: [advisory only, non-blocking — 1 sentence if needed]
+```
+
+There is no task file or INDEX.md to update in this mode. Findings are advisory only: the main
+task is not blocked on this review and may already be reported done by the time you finish.
+Report back to the caller in a few lines; do not paste the full diff.

package/templates/CLAUDE.md

@@ -128,6 +128,14 @@ Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+P
 - This is optional internal orchestration config from `.ukit/storage/config.json`; never turn it into an end-user workflow.
 - Always preserve the CoDev priority: quality > safety > speed > token discipline.
 
+## Post-Edit Sidecar Review (internal)
+
+- If routed state's `routeSummary.line` includes a `review=code-reviewer(diff)` segment, a `local-build` or `shared-edit` task qualifies for a non-blocking second opinion — this exists because the daily-flow executor model can miss edge cases.
+- Only launch it once write evidence AND verification evidence already exist for the task (never before; never as a substitute for either).
+- Launch the `code-reviewer` agent via the Agent tool with `REVIEW_TARGET_TYPE=diff` and `run_in_background: true` (model `unic-smart` per `subagents.diffReviewModel`). Do not wait for it — continue and report the task as done using the normal completion rules.
+- Its findings are advisory only: never re-open, block, or delay the already-reported completion on their account. Surface them to the user as a follow-up note if/when they arrive.
+- This is internal orchestration — end users never invoke it directly; `ukit install` plus natural language remains the whole surface. No new commands.
+
 ## Selective Subagent Policy (internal only)
 
 - Keep direct execution as the default for trivial/simple work.

package/templates/ukit/storage/config.json

@@ -105,8 +105,9 @@
         "maxReadPasses": 2,
         "maxContextPulls": 1,
         "verificationPolicy": "targeted-if-covered",
-        "completionRule": "require-write",
-        "delegationPolicy": "disallow-by-default"
+        "completionRule": "require-write-and-verification",
+        "delegationPolicy": "disallow-by-default",
+        "postEditReviewPolicy": "sidecar-non-blocking"
       },
       "find-cause": {
         "modelTier": "code",
@@ -121,7 +122,8 @@
         "maxContextPulls": 2,
         "verificationPolicy": "targeted-then-widen-on-risk",
         "completionRule": "require-write-and-verification",
-        "delegationPolicy": "allow-qualified-sidecar"
+        "delegationPolicy": "allow-qualified-sidecar",
+        "postEditReviewPolicy": "sidecar-non-blocking"
       },
       "map-impact": {
         "modelTier": "code",
@@ -241,6 +243,9 @@
     "enabled": true,
     "smallTaskModel": "unic-lite",
     "smallTaskAgent": "ukit-small-task-maintainer",
+    "diffReviewEnabled": true,
+    "diffReviewAgent": "code-reviewer",
+    "diffReviewModel": "unic-smart",
     "visionEnabled": true,
     "visionModel": "unic-vision",
     "visionAgent": "ukit-vision-analyst",