@ngockhoale/ukit 1.4.1 → 1.4.2

package/templates/.claude/ukit/runtime/reinject-context.mjs

@@ -51,6 +51,7 @@ async function main() {
 
   const dynamicLines = [
     ...await buildRouteStateLines(state),
+    ...buildApproachSelectorLines(state),
     ...await buildPreviousContextLines(projectRoot, state, config),
     ...await buildRecentOutputLines(projectRoot, config),
     ...await buildResolverHintLines(projectRoot, state),
@@ -63,6 +64,11 @@ async function main() {
   const pressureState = await readCompactPressureState(projectRoot, config);
   const anchorLines = dynamicLines.filter((line) => (
     line.startsWith('- Recent routed lane:')
+    || line.startsWith('- Current approach:')
+    || line.startsWith('- Completion debt:')
+    || line.startsWith('- Continuation required:')
+    || line.startsWith('- Stuck-lane rescue:')
+    || line.startsWith('- Continue rule:')
     || line.startsWith('- Previous context:')
     || line.startsWith('- Recent command output:')
     || line.startsWith('- Recent delegation hint:')
@@ -394,9 +400,16 @@ function deriveNextActionSegment(state) {
 }
 
 function deriveNextActionType(state) {
-  return hasStructuredRouteSummaryField(state, 'nextActionType')
-    ? (state?.routeSummary?.nextActionType || '')
-    : (state?.nextAction?.type || '');
+  if (hasStructuredRouteSummaryField(state, 'nextActionType')) {
+    return state?.routeSummary?.nextActionType || '';
+  }
+
+  if (state?.nextAction?.type) {
+    return state.nextAction.type;
+  }
+
+  const nextSegment = extractSegment(state?.routeSummary?.line || '', 'next');
+  return nextSegment ? String(nextSegment).replace(/^next=/, '').trim() : '';
 }
 
 function inferTargetSegmentFromHelperHint(helperHint) {
@@ -525,6 +538,110 @@ async function buildRouteStateLines(state) {
   return lines;
 }
 
+function buildApproachSelectorLines(state = {}) {
+  const approachSelector = deriveApproachSelector(state);
+  const lines = [];
+  if (approachSelector) {
+    const approachSegments = [
+      approachSelector.executionMode || null,
+      approachSelector.riskLevel ? `risk=${approachSelector.riskLevel}` : null,
+      approachSelector.contextPolicy ? `context=${approachSelector.contextPolicy}` : null,
+      approachSelector.verificationPolicy ? `verify=${approachSelector.verificationPolicy}` : null,
+    ].filter(Boolean);
+
+    if (approachSegments.length > 0) {
+      lines.push('- Current approach: ' + approachSegments.join(' | '));
+    }
+
+    const missingEvidence = unique(state?.routeSummary?.completionState?.missingEvidence ?? []);
+    if (missingEvidence.length > 0) {
+      const completionRule = approachSelector.completionRule
+        || state?.routeSummary?.executionContract?.completionRule
+        || null;
+      lines.push('- Completion debt: ' + missingEvidence.join(', ') + (completionRule ? ` | gate=${completionRule}` : ''));
+      lines.push('- Continue rule: while completion debt remains, do not end with done/applied/fixed language unless a real blocker is found.');
+    }
+  }
+
+  const continuationState = deriveContinuationState(state);
+  if (continuationState?.required) {
+    const reasonText = unique(continuationState.reasons ?? []).join(', ');
+    lines.push('- Continuation required: yes' + (reasonText ? ` | reasons=${reasonText}` : '') + (continuationState.nextMilestone ? ` | next=${continuationState.nextMilestone}` : ''));
+    if (Number(continuationState.repeatCount ?? 0) >= 2 || continuationState.rescueMode) {
+      lines.push('- Stuck-lane rescue: active'
+        + ` | repeats=${Number(continuationState.repeatCount ?? 0)}`
+        + (continuationState.stuckRisk ? ` | risk=${continuationState.stuckRisk}` : '')
+        + (continuationState.rescueMode ? ` | mode=${continuationState.rescueMode}` : ''));
+    }
+    if ((continuationState.reasons ?? []).includes('pending-bounded-context')) {
+      lines.push('- Continue rule: pull-indexed-context is an internal continuation step; after the bounded read, continue to edit/verify in the same turn when safe.');
+    }
+  }
+
+  return lines;
+}
+
+function deriveApproachSelector(state = {}) {
+  const explicit = state?.routeSummary?.approachSelector;
+  if (explicit && typeof explicit === 'object') {
+    return explicit;
+  }
+
+  const executionMode = state?.routeSummary?.executionMode
+    || state?.routingContext?.executionMode
+    || null;
+  if (!executionMode) {
+    return null;
+  }
+
+  return {
+    executionMode,
+    verificationPolicy: state?.routeSummary?.executionContract?.verificationPolicy || null,
+    completionRule: state?.routeSummary?.executionContract?.completionRule || null,
+  };
+}
+
+function deriveContinuationState(state = {}) {
+  const explicit = state?.routeSummary?.continuationState;
+  if (explicit && typeof explicit === 'object') {
+    return explicit;
+  }
+
+  const nextActionType = deriveNextActionType(state);
+  const missingEvidence = unique(state?.routeSummary?.completionState?.missingEvidence ?? []);
+  const reasons = [];
+
+  if (nextActionType === 'pull-indexed-context') {
+    reasons.push('pending-bounded-context');
+  }
+  if (missingEvidence.includes('write-evidence')) {
+    reasons.push('missing-write-evidence');
+  }
+  if (missingEvidence.includes('verification-evidence') || missingEvidence.includes('verification-plan')) {
+    reasons.push('missing-verification-evidence');
+  }
+  if (missingEvidence.includes('impact-evidence')) {
+    reasons.push('missing-impact-evidence');
+  }
+
+  if (reasons.length === 0) {
+    return null;
+  }
+
+  return {
+    required: true,
+    reasons,
+    doneLanguageBlocked: true,
+    stopAllowedOnlyFor: ['real-blocker'],
+    nextMilestone: reasons.includes('pending-bounded-context')
+      ? 'complete-bounded-context-then-continue'
+      : null,
+    repeatCount: 1,
+    stuckRisk: null,
+    rescueMode: null,
+  };
+}
+
 async function buildRecentOutputLines(projectRoot, config) {
   if (!config?.tokenPipeline?.outputCompression) {
     return [];

package/templates/.codex/README.md

@@ -12,7 +12,7 @@ Auto-generated by UKit for OpenAI Codex.
 - Do not make end users memorize skill names, helper scripts, or routing internals unless they are debugging UKit itself.
 - **Treat helper commands as internal orchestration. Do not ask end users to run them.**
 
-## UKit v1.4.1 Shared Runtime
+## UKit v1.4.2 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
 - Treat `.ukit/storage/config.json` as the source of compact, token-pipeline, router, memory, validation, and Safe Patch guardrail toggles.
@@ -82,6 +82,13 @@ After significant work, update only what changed:
 - `docs/CODE_MAP.md`
 - `docs/PROJECT.md`
 
+## Execution Contract
+
+- For explicit implement/apply/fix requests, continue until the actual edit is made or a real blocker is found; do not stop after a read-only inspection step.
+- If routed state still says `pull-indexed-context`, treat it as an internal continuation step, not a stopping point; after the bounded read, continue to edit/verify in the same turn when safe.
+- If routed state shows `continuation required` or a stuck-lane rescue mode, finish the named milestone before widening reads or repeating the same partial analysis.
+- Do not say “done”, “applied”, or “fixed” after Read/Grep/analysis alone. Completion wording requires concrete Edit/Write evidence in the current turn, and verification when the scope is risky.
+
 ## Skills
 
 Skills are shared from `.claude/skills/` via symlink at `.codex/skills/`.

package/templates/.codex/settings.json

@@ -258,6 +258,59 @@
       },
       "configPath": ".ukit/storage/config.json",
       "configField": "subagents.smallTaskModel"
+    },
+    "orchestration": {
+      "enabled": true,
+      "configPath": ".ukit/storage/config.json",
+      "modelField": "orchestration.orchestratorModel",
+      "advisorField": "orchestration.advisorEnabled",
+      "defaultModel": "claude-sonnet-4-6",
+      "internalOnly": true,
+      "qualityFirst": true,
+      "safeUpwardBias": true,
+      "layers": [
+        "tiny-fix",
+        "local-fix",
+        "local-build",
+        "find-cause",
+        "shared-edit",
+        "map-impact",
+        "review-release"
+      ],
+      "contracts": {
+        "tiny-fix": {
+          "maxReadPasses": 0,
+          "maxContextPulls": 0,
+          "completionRule": "never-claim-done-without-write"
+        },
+        "local-fix": {
+          "maxReadPasses": 1,
+          "maxContextPulls": 1,
+          "completionRule": "require-write"
+        },
+        "local-build": {
+          "maxReadPasses": 2,
+          "maxContextPulls": 1,
+          "completionRule": "require-write"
+        },
+        "find-cause": {
+          "maxReadPassesBeforeReassess": 3,
+          "completionRule": "never-claim-fixed-without-write-and-verification"
+        },
+        "shared-edit": {
+          "maxReadPasses": 2,
+          "maxContextPulls": 2,
+          "completionRule": "require-write-and-verification"
+        },
+        "map-impact": {
+          "maxReadPasses": 3,
+          "maxContextPulls": 3,
+          "completionRule": "require-impact-evidence-before-edit-claim"
+        },
+        "review-release": {
+          "completionRule": "report-findings-not-implementation"
+        }
+      }
     }
   },
   "execution": {

package/templates/AGENTS.md

@@ -107,6 +107,9 @@
 - Do not teach normal contributors `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` unless they are explicitly debugging UKit itself.
 - If the workspace needs a refresh, prefer telling them to rerun `ukit install`.
 - Keep scope tight, prefer the smallest correct change set, reuse existing code, and update docs when source changes.
+- For explicit implement/apply/fix work, if routed state still says `pull-indexed-context`, treat it as internal continuation, not a stopping point; continue through the bounded read into edit/verify when safe.
+- If routed state shows `continuation required` or a stuck-lane rescue mode, finish the named milestone before widening reads or repeating a partial progress report.
+- Never end with “done/applied/fixed” language while write/verification evidence is still missing unless there is a real blocker.
 
 ## Environment Snapshot
 

package/templates/CLAUDE.md

@@ -42,7 +42,7 @@
 - **Do not ask normal contributors to run internal helper commands**; run them yourself or tell them to rerun `ukit install`.
 - Do not ask normal contributors to memorize `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` unless they explicitly need maintainer/debug help.
 
-## UKit v1.4.1 Shared Runtime
+## UKit v1.4.2 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
 - Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, validation, and Safe Patch behavior.
@@ -113,6 +113,10 @@
 
 - Keep scope tight.
 - Reuse existing code.
+- For explicit implement/apply/fix requests, keep working until the actual edit is made or a real blocker is found; do not stop after a read-only inspection step.
+- If routed state still says `pull-indexed-context`, treat it as an internal continuation step, not a stopping point; after the bounded read, continue to edit/verify in the same turn when safe.
+- If routed state shows `continuation required` or a stuck-lane rescue mode, finish the named milestone before widening reads or rephrasing the same partial status.
+- Never claim “done”, “applied”, or “fixed” after Read/Grep/analysis alone. Completion language requires concrete Edit/Write evidence in the current turn, plus verification when the change is risky.
 - Update `docs/WORKLOG.md` after significant work.
 - If source contradicts docs, update docs immediately.
 - Use `{{runtime.packageManager}}`.

package/templates/ukit/README.md

@@ -1,6 +1,6 @@
 # UKit Shared Runtime
 
-This folder stores shared UKit runtime state for v1.4.1 features.
+This folder stores shared UKit runtime state for v1.4.2 features.
 
 - `storage/config.json` — runtime feature flags and defaults
 - `storage/cache/` — prompt-cache, compact history, compact pressure state, output summaries, and preserved raw tool outputs under `storage/cache/tee/`

package/templates/ukit/storage/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.4.1",
+  "version": "1.4.2",
   "agent": "claude-code",
   "autonomy": {
     "level": "balanced",
@@ -76,6 +76,59 @@
     "advisorEnabled": true,
     "maxAdvisorCalls": 3
   },
+  "orchestration": {
+    "enabled": true,
+    "orchestratorModel": "claude-sonnet-4-6",
+    "advisorEnabled": true,
+    "contracts": {
+      "tiny-fix": {
+        "maxReadPasses": 0,
+        "maxContextPulls": 0,
+        "verificationPolicy": "minimal-or-targeted",
+        "completionRule": "never-claim-done-without-write",
+        "delegationPolicy": "disallow"
+      },
+      "local-fix": {
+        "maxReadPasses": 1,
+        "maxContextPulls": 1,
+        "verificationPolicy": "targeted-if-covered",
+        "completionRule": "require-write",
+        "delegationPolicy": "disallow"
+      },
+      "local-build": {
+        "maxReadPasses": 2,
+        "maxContextPulls": 1,
+        "verificationPolicy": "targeted-if-covered",
+        "completionRule": "require-write",
+        "delegationPolicy": "disallow-by-default"
+      },
+      "find-cause": {
+        "maxReadPassesBeforeReassess": 3,
+        "verificationPolicy": "root-cause-then-targeted",
+        "completionRule": "never-claim-fixed-without-write-and-verification",
+        "delegationPolicy": "allow-specialized-debug-lane"
+      },
+      "shared-edit": {
+        "maxReadPasses": 2,
+        "maxContextPulls": 2,
+        "verificationPolicy": "targeted-then-widen-on-risk",
+        "completionRule": "require-write-and-verification",
+        "delegationPolicy": "allow-qualified-sidecar"
+      },
+      "map-impact": {
+        "maxReadPasses": 3,
+        "maxContextPulls": 3,
+        "verificationPolicy": "impact-first-then-targeted-then-widen-on-risk",
+        "completionRule": "require-impact-evidence-before-edit-claim",
+        "delegationPolicy": "allow-impact-sidecar"
+      },
+      "review-release": {
+        "verificationPolicy": "evidence-first",
+        "completionRule": "report-findings-not-implementation",
+        "delegationPolicy": "allow-review-sidecar"
+      }
+    }
+  },
   "memory": {
     "enabled": true,
     "autoCapture": true,
@@ -270,6 +323,12 @@
       "advisorEnabled": "Cho phép advisor-style planning cho task phức tạp.",
       "maxAdvisorCalls": "Giới hạn số lần gọi advisor để không lãng phí."
     },
+    "orchestration": {
+      "enabled": "Bật ladder điều phối nội bộ của UKit. Ladder này thay cách nghĩ LITE/FULL cứng nhắc bằng các tầng tiny-fix → review-release an toàn hơn.",
+      "orchestratorModel": "Model điều phối chất lượng cao để chọn execution layer. Đây là model quan trọng cho chất lượng completion, không nên dùng model quá yếu.",
+      "advisorEnabled": "Cho phép UKit dùng advisor-style reasoning khi chọn layer trong tình huống mơ hồ.",
+      "contracts": "Bộ contract cho 7 tầng điều phối: tiny-fix, local-fix, local-build, find-cause, shared-edit, map-impact, review-release. Khi mơ hồ, UKit nên lệch lên tầng an toàn hơn dù tốn token hơn."
+    },
     "memory": {
       "enabled": "Bật memory local của UKit.",
       "autoCapture": "Cho phép UKit lưu decision/rule bền vững khi an toàn.",
@@ -287,7 +346,7 @@
     },
     "subagents": {
       "enabled": "Cho phép UKit dùng các lane subagent nội bộ khi hữu ích.",
-      "smallTaskModel": "Model sidecar nội bộ cho quyết định nhỏ/an toàn của UKit. Đổi key này nếu muốn đổi model nội bộ.",
+      "smallTaskModel": "Model sidecar nội bộ cho quyết định nhỏ/an toàn của UKit. Đổi key này nếu muốn đổi model nội bộ. Nó không thay thế orchestration.orchestratorModel.",
       "smallTaskAgent": "Tên agent nội bộ phụ trách quyết định nhỏ không block task chính.",
       "smallTaskUseCases": "Các loại việc an toàn sidecar có thể xử lý: dọn task, compact decision, phân loại, triage, queue maintenance, workspace maintenance.",
       "keepMainModelFor": "Các việc rủi ro phải giữ ở main model: security, code risky, release, data-loss, architecture, deep reasoning.",