@ngockhoale/ukit 1.4.4 → 1.5.1

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to UKit are documented here.
 
+## 1.5.0 - 2026-05-24
+
+### Fixed
+
+- Switched safe-patch release regressions to `spawnSync`-based helpers so advisory-mode assertions capture `stderr` correctly even when the hook exits `0`.
+- Raised the packed artifact size budget slightly to preserve the shipped canvas font lane and recent runtime/router surfaces without failing release smoke on a 625-byte overage.
+
+### Changed
+
+- Bumped package and shared runtime version metadata to `1.5.0`.
+
+## 1.4.5 - 2026-05-24
+
+### Fixed
+
+- Stopped safe-patch hooks (`stale-spec-check`, `post-edit-verify`) from hard-blocking tool calls when configured via the new `safePatch.advisoryOnly` flag or the `UKIT_SAFE_PATCH_ADVISORY=1` env. Removes the mid-task "stop and wait for continue" stalls that hit shared-risk files in `.claude/`, `templates/`, `scripts/`, etc., while preserving the diagnostic message so Claude/Codex can self-correct instead of stalling.
+- Default behavior unchanged (`advisoryOnly: false`): pre-edit corruption guards (shebang-bom, non-text, whole-file Write to shared-risk) and the `protect-files` / `block-dangerous` hooks still hard-block.
+
+### Tests
+
+- Added regression coverage for advisory-mode exit code and stderr in `tests/hooks/safePatchProtocol.test.js`.
+- Added default + validation assertions for `safePatch.advisoryOnly` in `tests/core/runtimeConfig.test.js`.
+
 ## 1.4.4 - 2026-05-11
 
 ### Fixed

package/manifests/platform.full.yaml

@@ -84,7 +84,7 @@ items:
     requires:
       - docs-project
       - docs-memory
-    mergeStrategy: skip
+    mergeStrategy: overwrite_with_backup
     variables:
       - project.name
       - project.root
@@ -107,7 +107,7 @@ items:
     requires:
       - docs-project
       - docs-memory
-    mergeStrategy: skip
+    mergeStrategy: overwrite_with_backup
     variables:
       - project.name
       - project.stack
@@ -1302,6 +1302,15 @@ items:
     packs:
       - core
 
+  - id: multi-antigravity-agents-link
+    type: link
+    sourceTemplate: .claude/agents
+    targetPath: .antigravity/agents
+    requires: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: multi-antigravity-rules
     type: config
     sourceTemplate: adapter-presets/antigravity/rules.md
@@ -1349,6 +1358,15 @@ items:
     packs:
       - core
 
+  - id: multi-codex-agents-link
+    type: link
+    sourceTemplate: .claude/agents
+    targetPath: .codex/agents
+    requires: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: multi-codex-readme
     type: config
     sourceTemplate: .codex/README.md

package/package.json

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

package/src/cli/adapters.js

@@ -7,12 +7,14 @@ export const OPTIONAL_ADAPTERS = [
       'multi-antigravity-ukit-link',
       'multi-antigravity-rules',
       'multi-antigravity-readme',
+      'multi-antigravity-agents-link',
     ],
     managedPaths: [
       '.antigravity/skills',
       '.antigravity/ukit',
       '.antigravity/rules/rules.md',
       '.antigravity/README.md',
+      '.antigravity/agents',
     ],
   },
   {
@@ -24,6 +26,7 @@ export const OPTIONAL_ADAPTERS = [
       'multi-codex-readme',
       'multi-codex-settings-json',
       'multi-codex-settings-local',
+      'multi-codex-agents-link',
     ],
     managedPaths: [
       '.codex/skills',
@@ -31,6 +34,7 @@ export const OPTIONAL_ADAPTERS = [
       '.codex/README.md',
       '.codex/settings.json',
       '.codex/settings.local.json',
+      '.codex/agents',
     ],
   },
   {

package/src/core/applyPlan.js

@@ -2,6 +2,16 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { writeFileAtomic, copyFileSafe, createDirectoryLink, removeLinkOnly } from './fileOps.js';
 
+const TCC_PROTECTED_PREFIXES = ['.codex/', '.antigravity/'];
+
+function isTccProtectedPath(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  return TCC_PROTECTED_PREFIXES.some((prefix) => {
+    const idx = normalized.indexOf(`/${prefix}`);
+    return idx !== -1 || normalized.startsWith(prefix);
+  });
+}
+
 export async function applyDiffResults(diffResults, { backupRoot, projectRoot } = {}) {
   const writes = [];
   let skippedUpdates = 0;
@@ -12,14 +22,9 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
     }
 
     if (entry.type === 'link') {
-      // Remove existing symlink before recreating.
-      // Use removeLinkOnly — NOT removeLinkOrDir — to protect real directories that may
-      // contain user content. If the path is not a symlink, skip and warn instead of
-      // recursively deleting it.
       if (entry.action === 'update') {
         const removed = await removeLinkOnly(entry.targetPath);
         if (!removed) {
-          // Determine what actually exists at this path for a precise warning message.
           let existingKind = 'unknown path';
           try {
             const stat = await fs.lstat(entry.targetPath);
@@ -34,7 +39,18 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
           continue;
         }
       }
-      await createDirectoryLink(entry.linkTarget, entry.targetPath);
+      try {
+        await createDirectoryLink(entry.linkTarget, entry.targetPath);
+      } catch (linkError) {
+        if (linkError.code === 'EPERM' || linkError.code === 'EACCES') {
+          console.warn(
+            `[UKit] Warning: skipping link creation for ${entry.targetPath} — permission denied. Run 'ukit install' from within the target tool to create it.`,
+          );
+          skippedUpdates += 1;
+          continue;
+        }
+        throw linkError;
+      }
       writes.push({
         id: entry.id,
         targetPath: entry.targetPath,
@@ -54,7 +70,18 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
       const relPath = path.relative(projectRoot, entry.targetPath);
       const timestamp = Date.now();
       const backupPath = path.join(backupRoot, `${relPath}.${timestamp}.bak`);
-      await copyFileSafe(entry.targetPath, backupPath);
+      try {
+        await copyFileSafe(entry.targetPath, backupPath);
+      } catch (backupError) {
+        if (backupError.code === 'EPERM' || backupError.code === 'EACCES') {
+          console.warn(
+            `[UKit] Warning: skipping backup for ${entry.targetPath} — permission denied.`,
+          );
+          skippedUpdates += 1;
+          continue;
+        }
+        throw backupError;
+      }
     }
 
     const binaryEntry = Buffer.isBuffer(entry.renderedContent);
@@ -73,7 +100,21 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
           )
           : entry.renderedContent;
 
-    await writeFileAtomic(entry.targetPath, nextContent);
+    try {
+      await writeFileAtomic(entry.targetPath, nextContent);
+    } catch (writeError) {
+      if (
+        (writeError.code === 'EPERM' || writeError.code === 'EACCES') &&
+        isTccProtectedPath(entry.targetPath)
+      ) {
+        console.warn(
+          `[UKit] Warning: skipping write for ${entry.targetPath} — permission denied (macOS TCC). Run 'ukit install' from within the owning tool to update it.`,
+        );
+        skippedUpdates += 1;
+        continue;
+      }
+      throw writeError;
+    }
     if (typeof entry.mode === 'number') {
       await fs.chmod(entry.targetPath, entry.mode);
     }

package/src/core/runtimeConfig.js

@@ -49,7 +49,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
   const safeOverrides = isPlainObject(overrides) ? overrides : {};
 
   return mergeObjects({
-    version: '1.4.4',
+    version: '1.5.1',
     agent: 'claude-code',
     autonomy: {
       level: 'balanced',
@@ -183,6 +183,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
     safePatch: {
       enabled: true,
       strictSharedRisk: true,
+      advisoryOnly: false,
       largeFileLineThreshold: 800,
       largeFileByteThreshold: 200_000,
       backupEnabled: true,
@@ -368,6 +369,7 @@ export function validateRuntimeConfig(config) {
   } else {
     pushBooleanError(errors, config.safePatch.enabled, 'safePatch.enabled');
     pushBooleanError(errors, config.safePatch.strictSharedRisk, 'safePatch.strictSharedRisk');
+    pushBooleanError(errors, config.safePatch.advisoryOnly, 'safePatch.advisoryOnly');
     pushPositiveNumberError(errors, config.safePatch.largeFileLineThreshold, 'safePatch.largeFileLineThreshold');
     pushPositiveNumberError(errors, config.safePatch.largeFileByteThreshold, 'safePatch.largeFileByteThreshold');
     pushBooleanError(errors, config.safePatch.backupEnabled, 'safePatch.backupEnabled');

package/src/manifest/selectItems.js

@@ -3,11 +3,13 @@ export const OPTIONAL_ADAPTER_ITEM_IDS = new Set([
   'multi-antigravity-ukit-link',
   'multi-antigravity-rules',
   'multi-antigravity-readme',
+  'multi-antigravity-agents-link',
   'multi-codex-skills-link',
   'multi-codex-ukit-link',
   'multi-codex-readme',
   'multi-codex-settings-json',
   'multi-codex-settings-local',
+  'multi-codex-agents-link',
   'multi-opencode-config',
 ]);
 

package/templates/.claude/agents/ukit-small-task-maintainer.md

@@ -1,7 +1,7 @@
 ---
 name: ukit-small-task-maintainer
 description: "Internal UKit maintenance subagent for low-risk, reversible UKit decisions. Use proactively when UKit needs to decide or perform safe cleanup such as pruning docs/TASKS.md, classifying queued work, choosing whether compact/summarization is appropriate, summarizing local docs/status, or maintaining small UKit runtime queues. Do not use for product implementation, security, release/publish, data-loss, architecture, or risky/shared code changes."
-model: inherit
+model: unic-lite
 color: cyan
 tools: ["Read", "Grep", "Glob", "Edit", "Write"]
 ---

package/templates/.claude/ukit/index/post-edit-verify.mjs

@@ -2,7 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { analyzeTextBuffer, analyzeTextFile, publicTextProfile } from '../runtime/text-profile.mjs';
-import { classifySafePatchRisk, parseJsonInput, pathExists, readRuntimeSafePatchConfig, resolveProjectFile } from '../runtime/safe-patch-core.mjs';
+import { classifySafePatchRisk, isSafePatchAdvisoryOnly, parseJsonInput, pathExists, readRuntimeSafePatchConfig, resolveProjectFile } from '../runtime/safe-patch-core.mjs';
 
 async function readStdin() {
   return await new Promise((resolve) => {
@@ -183,8 +183,10 @@ async function main() {
     process.stdout.write(json ? `${JSON.stringify({ help: text })}\n` : `${text}\n`);
     return;
   }
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const runtimeConfig = await readRuntimeSafePatchConfig(projectRoot);
   const result = await verifyPostEdit({
-    projectRoot: process.env.CLAUDE_PROJECT_DIR || process.cwd(),
+    projectRoot,
     payload: parseJsonInput(await readStdin(), {}),
   });
   if (json) {
@@ -193,7 +195,14 @@ async function main() {
     process.stdout.write(`[ukit-safe-patch] ${result.message}\n`);
   }
   if (result.status === 'blocked') {
-    process.stderr.write(`[ukit-safe-patch] ${result.message}\n`);
+    const advisory = isSafePatchAdvisoryOnly(runtimeConfig);
+    const prefix = advisory ? 'ADVISORY' : 'BLOCKED';
+    const message = String(result.message || '').replace(/^BLOCKED:/, `${prefix}:`);
+    process.stderr.write(`[ukit-safe-patch] ${message}\n`);
+    if (advisory) {
+      process.stderr.write('[ukit-safe-patch] advisoryOnly=true — change is already written; continue planned follow-up without stopping.\n');
+      return;
+    }
     process.exit(2);
   }
 }

package/templates/.claude/ukit/index/stale-spec-check.mjs

@@ -4,6 +4,7 @@ import path from 'node:path';
 import {
   classifySafePatchRisk,
   countOccurrences,
+  isSafePatchAdvisoryOnly,
   lineNumberForIndex,
   parseJsonInput,
   pathExists,
@@ -169,7 +170,9 @@ async function main() {
     return;
   }
   const payload = parseJsonInput(await readStdin(), {});
-  const result = await checkStaleSpec({ projectRoot: process.env.CLAUDE_PROJECT_DIR || process.cwd(), payload });
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const runtimeConfig = await readRuntimeSafePatchConfig(projectRoot);
+  const result = await checkStaleSpec({ projectRoot, payload });
   if (args.json) {
     process.stdout.write(`${JSON.stringify(result)}\n`);
   } else if (result.status === 'ok') {
@@ -179,7 +182,14 @@ async function main() {
   }
 
   if (result.status === 'blocked') {
-    process.stderr.write(`[ukit-safe-patch] ${result.message}\n`);
+    const advisory = isSafePatchAdvisoryOnly(runtimeConfig);
+    const prefix = advisory ? 'ADVISORY' : 'BLOCKED';
+    const message = String(result.message || '').replace(/^BLOCKED:/, `${prefix}:`);
+    process.stderr.write(`[ukit-safe-patch] ${message}\n`);
+    if (advisory) {
+      process.stderr.write('[ukit-safe-patch] advisoryOnly=true — continue with corrected old_string; do not stop and ask the user.\n');
+      return;
+    }
     process.exit(2);
   }
 }

package/templates/.claude/ukit/runtime/safe-patch-core.mjs

@@ -4,6 +4,7 @@ import path from 'node:path';
 export const DEFAULT_SAFE_PATCH_CONFIG = {
   enabled: true,
   strictSharedRisk: true,
+  advisoryOnly: false,
   largeFileLineThreshold: 800,
   largeFileByteThreshold: 200_000,
   backupEnabled: true,
@@ -13,6 +14,15 @@ export const DEFAULT_SAFE_PATCH_CONFIG = {
   deltaMaxDiffCells: 2_000_000,
 };
 
+// When advisoryOnly is true (via config or env UKIT_SAFE_PATCH_ADVISORY=1),
+// safe-patch hooks downgrade exit 2 (block) to exit 0 + WARNING. This keeps
+// Claude/Codex from stalling mid-task on stale/ambiguous spec or delta-budget
+// trips without losing the diagnostic message.
+export function isSafePatchAdvisoryOnly(config = DEFAULT_SAFE_PATCH_CONFIG) {
+  if (process.env.UKIT_SAFE_PATCH_ADVISORY === '1') return true;
+  return Boolean(config?.advisoryOnly);
+}
+
 const SHARED_RISK_PATTERNS = [
   /^\.claude\/hooks\//,
   /^\.claude\/ukit\//,

package/templates/.codex/README.md

@@ -5,66 +5,121 @@ Auto-generated by UKit for OpenAI Codex.
 - Packs: {{project.stack}}
 - Package manager: {{runtime.packageManager}}
 
-## Team Workflow (Highest Priority)
+## Core UKit Rule
 
-- Teammates should only need to remember **`ukit install`**.
-- After `ukit install`, open Claude/Codex and ask naturally.
-- 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.**
+- Human-facing workflow should optimize for one remembered command: `ukit install`.
+- After install, normal work should feel natural inside **Claude/Codex/OpenCode** (and Antigravity when installed).
+- **Quality first, then speed, then token discipline**: do not waste reads, logs, or repeated helper output.
+- **Never stop after read-only steps.** For implement/apply/fix requests, continue to actual Edit/Write and verification in the same turn.
 
-## UKit v1.4.3 Shared Runtime
+## Fast Task Classification
 
-- 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.
-- Reuse `.ukit/storage/memory/` before asking users to restate prior decisions.
-- For non-trivial work, prefer `ukit memory recall "<current task>"` before widening docs.
-- Reusable cache state lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, `.ukit/storage/cache/compact-pressure.json`, `.ukit/storage/cache/output-history.json`, and preserved raw tool outputs under `.ukit/storage/cache/tee/`.
-- If an older repo still has a visible `ukit/` runtime root, rerun `ukit install`; UKit should migrate the shared runtime into hidden `.ukit/` when safe.
-- Maintainers can inspect runtime state with `ukit status` and `ukit memory export`.
-- Reuse compact `previous-context` / `recent-output` route snapshots before replaying raw history.
-- Threshold-based compact pressure is internal orchestration; Codex users should not need to manage it manually.
-- UKit keeps Claude PreCompact/reinject and OpenCode native auto/prune compaction intact. For Codex Desktop long sessions, UKit can use `subagents.smallTaskModel` through `ukit-small-task-maintainer` to decide soft auto-compact handoffs. Default `compact.codexContext.compactTarget=150` means about 150 compact handoff lines (120-150 preferred, hard max 170), not 150 app-context tokens.
-- Safe Patch Protocol is internal: for risky file edits, prefer current-file anchors and exact specs, avoid whole-file rewrites, and preserve multilingual/BOM/newline profiles. Do not ask normal users to run helper commands.
+- **Trivial** — typo, label, rename nhỏ, spacing, toggle flag, obvious config change.
+  - Act directly. No doc reads. No planning. No index.
+- **Simple** — 1-2 files, clear scope, existing pattern.
+  - Handle directly. Pull only the smallest useful context via resolver or targeted read.
+- **Non-trivial / Risky** — auth, security, migration, uninstall, shared runtime, race/flaky, data-loss.
+  - Read deeper, verify harder, and avoid shortcuts.
+  - Use index-first loop, then skill activation, then targeted verification.
 
-## Speed / Reading Contract
+## Execution Contract (mandatory)
 
-- **Trivial**: no docs.
-- **Simple**: `docs/MEMORY.md` only.
-- **Non-trivial**: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
-- `docs/STATUS.md`: read for open-ended status/continue prompts or meaningful continuation context; stale status is orientation only.
-- `docs/TASKS.md`: read only for queued-task prompts or when status points at queued work; safely clean exact duplicates/completed overflow by default without deleting unfinished human-authored tasks.
-- Read `docs/WORKLOG.md` only when recent continuation/debug context matters.
-- Source is truth; if docs are stale, update docs and continue.
+- 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 (Read/Grep/Glob/search).
+- If routed state says `pull-indexed-context`, treat it as internal continuation — 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 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.
+
+## Index-First Loop
 
-## Index-First Loop (for Codex)
+For any task that needs code context:
 
-1. Refresh/build the index only when needed:
+1. Check if index is fresh (`.cache/index/` artifacts). If stale or missing, refresh:
    - `node .codex/ukit/index/refresh-index.mjs`
    - fallback: `node .codex/ukit/index/build-index.mjs`
 2. Query likely files:
    - `node .codex/ukit/index/query-index.mjs "<error|symbol|path>"`
 3. For bug signatures:
    - `node .codex/ukit/index/triage.mjs "<error signature>"`
-4. Open only the top 1-3 suspect files first, then widen if needed.
+4. Open only the **top 1-3 suspect files first**, then widen if needed.
+5. For analog/reuse patterns, check if `resolve-context` returns related existing patterns.
 
-For clearly non-code specialist lanes, avoid dragging the source-code index into the route unless the target is actually code.
+For clearly non-code specialist lanes (docs-only, status, task queue), skip the source-code index.
 
-## Automatic Skill Activation
+## Automatic Skill Activation (mandatory)
 
 - End users should not need to know skill names.
-- For every non-trivial task — and again after the first meaningful tool calls — inspect installed project-local skills and **auto-activate the matching skill immediately**.
+- For every non-trivial task — and again after the first relevant tool calls — inspect installed project-local skills and **auto-activate the matching skill immediately**.
 - Match from prompt wording plus tool/file evidence.
-- Use the smallest useful set, usually 1-2 skills.
+- Use the smallest effective set, usually 1-2 skills.
 - If docs work is detected, prefer `.codex/skills/docs-quality/SKILL.md`.
-- For open-ended “what next?” / “continue” / project-status / queued-task prompts, prefer `.codex/skills/next-step/SKILL.md` and show a status freshness cue when status is used.
+- For open-ended "what next?" / "continue" / project-status / queued-task prompts, prefer `.codex/skills/next-step/SKILL.md` and show a status freshness cue when status is used.
 - For explicit handoff/wrap-up/status updates, prefer `.codex/skills/update-status/SKILL.md`.
 - Concrete debug/implementation/review prompts beat open-ended wording; do not let `next-step` replace the concrete workflow.
 - If routing is complex or ambiguous, prefer `node .codex/ukit/index/route-task.mjs "<prompt>" [--tool-command <cmd>] [--target <file>]`.
-- That helper should keep shared route memory in `.claude/ukit/skill-router-state.json` so Claude and Codex continue from the same compact route state.
+- Shared route memory in `.claude/ukit/skill-router-state.json` is shared across Claude and Codex.
 - When route memory already includes `previous-context` or `recent-output`, reuse it before widening reads or logs.
 - After routing, prefer `node .codex/ukit/index/resolve-context.mjs ...` for context and `node .codex/ukit/index/verify-context.mjs ...` for verification.
 - Follow routed verification policy: targeted first, widen only when scope/risk justifies it, ask before blanket broad runs.
 
+### Common skill triggers
+
+- review / audit / diff / PR feedback → `.codex/skills/code-review/SKILL.md`
+- bug / error / crash / triage / failing path → `.codex/skills/debugging-toolkit/SKILL.md`
+- test / spec / coverage / fixture → `.codex/skills/testing-quality/SKILL.md`
+- docs / README / changelog / handoff / editing `docs/` → `.codex/skills/docs-quality/SKILL.md`
+- open-ended next step / project status / continue → `.codex/skills/next-step/SKILL.md`
+- explicit handoff / wrap up / update `docs/STATUS.md` → `.codex/skills/update-status/SKILL.md`
+- auth / security / token / permission / validation → `.codex/skills/discover-security/SKILL.md`
+- stale workspace / reinstall / cleanup → `.codex/skills/repo-maintenance/SKILL.md`
+
+## Internal Helper Routing
+
+- If routing is complex or ambiguous, prefer `node .codex/ukit/index/route-task.mjs "<prompt>" [--tool-command <cmd>] [--target <file>]`.
+- If context is needed, prefer `node .codex/ukit/index/resolve-context.mjs ...`.
+- If verification is needed, prefer `node .codex/ukit/index/verify-context.mjs ...`.
+- **Treat helper commands as internal orchestration.** Run them yourself when needed; never ask end users to run them.
+
+## UKit v1.5.0 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.
+- Reuse `.ukit/storage/memory/` before asking users to restate prior decisions.
+- For non-trivial work, prefer `ukit memory recall "<current task>"` before widening doc reads.
+- Reusable cache state lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, `.ukit/storage/cache/compact-pressure.json`, `.ukit/storage/cache/output-history.json`, and preserved raw tool outputs under `.ukit/storage/cache/tee/`.
+- Shared route memory lives in `.claude/ukit/skill-router-state.json` (shared across Claude and Codex).
+- If an older repo still has a visible `ukit/` runtime root, rerun `ukit install`; UKit should migrate the shared runtime into hidden `.ukit/` when safe.
+- Maintainers can inspect runtime state with `ukit status` and `ukit memory export`.
+- Reuse compact `previous-context` / `recent-output` route snapshots before replaying raw history.
+- Threshold-based compact pressure is internal orchestration; Codex users should not need to manage it manually.
+- For Codex Desktop long sessions, UKit can use soft auto-compact handoffs. Default `compact.codexContext.compactTarget=150` means about 150 compact handoff lines (120-150 preferred, hard max 170), not 150 tokens.
+
+## Context + Verification Budget
+
+- **Trivial**: no docs.
+- **Simple**: `docs/MEMORY.md` only.
+- **Non-trivial**: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
+- `docs/STATUS.md`: read for open-ended status/continue prompts or meaningful continuation context; stale status is orientation only.
+- `docs/TASKS.md`: read only for queued-task prompts or when status points at queued work; safely clean exact duplicates/completed overflow by default without deleting unfinished human-authored tasks.
+- Read `docs/WORKLOG.md` only when recent continuation/debug context matters.
+- Source is truth; if docs are stale, update docs and continue.
+
+## Living Status Workflow
+
+- `docs/STATUS.md` is compact current state, not a transcript and not source truth.
+- When the user asks "what next?", "continue", without a concrete target, use the `next-step` skill and show a freshness cue (fresh / possibly stale / stale / missing).
+- Concrete debug/implementation/review prompts beat open-ended wording; use the concrete skill first and only use status as background.
+- After meaningful work, use `update-status` to record state, verification, blockers, and next candidates; skip trivial/no-state-change tasks.
+- `docs/TASKS.md` is a local AI task queue: prefer `Ready for AI` when asked to pick queued work, and clean duplicates/prune `Done Recently` safely.
+
+## Small-Task Maintainer (internal)
+
+- UKit may route low-risk internal decisions to the `ukit-small-task-maintainer` subagent using `subagents.smallTaskModel` (default `unic-lite`).
+- Use it for safe/reversible UKit chores: dọn `docs/TASKS.md`, queued-task classification, fast-vs-slow/safe-vs-risky lane decisions, skill-routing/step-budget hints, compact/summary decisions, docs/status summarization, auto-triage, queue maintenance, and small workspace cleanup.
+- Run it as a sidecar/parallel lane only; do not block, replace, or slow the user task.
+- If the small-task lane sees security, risky/shared code, release/publish, data-loss, architecture, deep-reasoning risk, weak context, or quality risk, it hands back to the main model.
+- Always preserve the CoDev priority: quality > safety > speed > token discipline.
+
 ## Selective Subagent Usage (internal only)
 
 - Stay direct for trivial/simple work or tightly coupled code already localized by the index.
@@ -72,6 +127,12 @@ For clearly non-code specialist lanes, avoid dragging the source-code index into
 - Good triggers: noisy side lanes, 3+ independent investigations, long-running background work, or explicit plan/batch execution.
 - End users still only need `ukit install`; subagent choice is internal orchestration.
 
+## Safe Patch Protocol
+
+- For risky/shared/large edits, prefer unique current-file anchors over line numbers or stale pasted blocks.
+- Do not silently merge stale specs: if `old_string` is missing or ambiguous, re-read current source and ask whether to apply as-is, adapt, or skip.
+- Preserve UTF-8 BOM/no-BOM and LF/CRLF for existing multilingual/user-authored files.
+
 ## Docs Discipline
 
 After significant work, update only what changed:
@@ -82,18 +143,29 @@ After significant work, update only what changed:
 - `docs/CODE_MAP.md`
 - `docs/PROJECT.md`
 
-## Execution Contract
+## Adaptive Autonomy
 
-- 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.
+- `autonomy.level` in `.ukit/storage/config.json` controls how much UKit acts without asking first: `conservative` (ask more), `balanced` (default), `free-run` (auto-run more).
+- End users should not need to change this; maintainers may tune it per-project.
 
 ## Skills
 
 Skills are shared from `.claude/skills/` via symlink at `.codex/skills/`.
 
+## Team Workflow Safety
+
+- 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.
+
 ## Codex Rulebase
 
 - `.codex/settings.json` — project-shared Codex safe-auto baseline
 - `.codex/settings.local.json` — machine-local overrides (kept on reinstall)
+
+## Completion Checklist
+
+- Requirements implemented
+- No unrelated changes
+- Verification executed and reported
+- Docs updated when source truth changed

package/templates/AGENTS.md

@@ -4,16 +4,42 @@
 
 - Human-facing workflow should optimize for one remembered command: `ukit install`.
 - After install, normal work should feel natural inside **Claude/Codex/OpenCode** (and Antigravity when installed).
-- Quality first, then speed, then token discipline: do not waste reads, logs, or repeated helper output.
+- **Quality first, then speed, then token discipline**: do not waste reads, logs, or repeated helper output.
+- **Never stop after read-only steps.** For implement/apply/fix requests, continue to actual Edit/Write and verification in the same turn.
 
 ## Fast Task Classification
 
 - **Trivial** — typo, label, rename nhỏ, spacing, toggle flag, obvious config change.
-  - Act directly. No doc reads. No planning.
+  - Act directly. No doc reads. No planning. No index.
 - **Simple** — 1-2 files, clear scope, existing pattern.
-  - Handle directly. Pull only the smallest useful context.
+  - Handle directly. Pull only the smallest useful context via resolver or targeted read.
 - **Non-trivial / Risky** — auth, security, migration, uninstall, shared runtime, race/flaky, data-loss.
   - Read deeper, verify harder, and avoid shortcuts.
+  - Use index-first loop, then skill activation, then targeted verification.
+
+## Execution Contract (mandatory)
+
+- 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 (Read/Grep/Glob/search).
+- If routed state says `pull-indexed-context`, treat it as internal continuation — 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 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.
+
+## Index-First Loop
+
+For any task that needs code context:
+
+1. Check if index is fresh (`.cache/index/` artifacts). If stale or missing, refresh:
+   - `node .claude/ukit/index/refresh-index.mjs`
+   - fallback: `node .claude/ukit/index/build-index.mjs`
+2. Query likely files:
+   - `node .claude/ukit/index/query-index.mjs "<error|symbol|path>"`
+3. For bug signatures:
+   - `node .claude/ukit/index/triage.mjs "<error signature>"`
+4. Open only the **top 1-3 suspect files first**, then widen if needed.
+5. For analog/reuse patterns, check if `resolve-context` returns related existing patterns.
+
+For clearly non-code specialist lanes (docs-only, status, task queue), skip the source-code index.
 
 ## Automatic Skill Activation (mandatory)
 
@@ -21,7 +47,6 @@
 - For every non-trivial task — and again after the first relevant tool calls — inspect installed project-local skills and **auto-activate the matching skill immediately**.
 - Match from both prompt wording and tool/file evidence.
 - Use the smallest effective set, usually 1-2 skills.
-- If the prompt/tool signals point to docs work, use `.claude/skills/docs-quality/SKILL.md` when present.
 - If evidence becomes more specific than the original prompt, upgrade the active skill choice immediately.
 - Prefer routed, compact context before widening manual reads.
 
@@ -43,18 +68,20 @@
 - If a concrete verification lane is needed, prefer `node .claude/ukit/index/verify-context.mjs ...`.
 - These helper/index commands are internal orchestration. Run them yourself when needed; never turn them into required end-user workflow.
 
-## UKit v1.3.1 Shared Runtime
+## UKit v1.5.1 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.
 - Reuse `.ukit/storage/memory/` before asking users to restate prior decisions.
 - For non-trivial work, prefer `ukit memory recall "<current task>"` before widening doc reads.
-- Reusable runtime cache lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, and `.ukit/storage/cache/output-history.json`.
+- Reusable runtime cache lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, `.ukit/storage/cache/compact-pressure.json`, `.ukit/storage/cache/output-history.json`, and preserved raw tool outputs under `.ukit/storage/cache/tee/`.
 - Shared route memory lives in `.claude/ukit/skill-router-state.json`.
 - If shared route state already includes compact `previous-context` or `recent-output` lines, reuse those first before rescanning memory or replaying noisy logs.
 - If an older repo still has a visible `ukit/` runtime root, rerun `ukit install`; UKit should migrate the shared runtime into hidden `.ukit/` when safe.
 - Maintainers can inspect runtime state with `ukit status` and `ukit memory export`, but normal teammates should still only need `ukit install`.
 - If runtime files are missing/corrupt, tell maintainers to rerun `ukit install`.
+- Threshold-based compact pressure is internal orchestration; do not expose it to users.
+- For Codex Desktop long sessions, UKit can use soft auto-compact handoffs. Default `compact.codexContext.compactTarget=150` means about 150 compact handoff lines (120-150 preferred, hard max 170), not 150 tokens.
 
 ## Context + Verification Budget
 
@@ -69,19 +96,19 @@
 ## Living Status Workflow
 
 - `docs/STATUS.md` is compact current state, not a transcript and not source truth.
-- When the user asks “what next?”, “continue”, or “project đang ở đâu?” without a concrete target, use the `next-step` skill and show a freshness cue (fresh / possibly stale / stale / missing).
+- When the user asks "what next?", "continue", or "project đang ở đâu?" without a concrete target, use the `next-step` skill and show a freshness cue (fresh / possibly stale / stale / missing).
 - Concrete debug/implementation/review prompts beat open-ended wording; use the concrete skill first and only use status as background.
 - After meaningful work, use `update-status` to record state, verification, blockers, and next candidates; skip trivial/no-state-change tasks.
 - `docs/TASKS.md` is a local AI task queue: prefer `Ready for AI` when asked to pick queued work, and clean duplicates/prune `Done Recently` safely when reading/updating it.
-- Detailed task context files such as `docs/context/<slug>.md` are a future extension, not required baseline workflow.
-
 
 ## Small-Task Maintainer (internal)
 
 - UKit may route low-risk internal decisions to the `ukit-small-task-maintainer` subagent using `subagents.smallTaskModel` (default `unic-lite`).
 - Use it for safe/reversible UKit chores: dọn `docs/TASKS.md`, queued-task classification, fast-vs-slow/safe-vs-risky lane decisions, skill-routing/step-budget hints, agent context-budget decisions, compact/summary decisions, docs/status summarization, auto-triage, queue maintenance, and small workspace cleanup.
-- Run it as a sidecar/parallel lane only; do not block, replace, or slow the user task. Do not block the main AI flow: if the small-task lane sees security, risky/shared code, release/publish, data-loss, architecture, deep-reasoning risk, weak context, or quality risk, it hands back to the main model instead of asking the end user to decide.
-- This is optional internal orchestration config from `.ukit/storage/config.json`; never turn it into an end-user workflow. End users still only need `ukit install` and natural-language product work. Always preserve the CoDev priority: quality > safety > speed > token discipline. Keep Claude PreCompact/reinject and OpenCode native auto/prune compaction enabled. For Codex Desktop long sessions, `compact.codexContext.compactTarget` defaults to 150 compact handoff lines (120-150 preferred, hard max 170), decided internally by the small-task maintainer.
+- Run it as a sidecar/parallel lane only; do not block, replace, or slow the user task.
+- If the small-task lane sees security, risky/shared code, release/publish, data-loss, architecture, deep-reasoning risk, weak context, or quality risk, it hands back to the main model.
+- 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.
 
 ## Subagent Policy (internal only)
 
@@ -100,16 +127,28 @@
 - Safe Patch is internal orchestration: normal users still only need `ukit install` and natural language.
 - For risky/shared/large edits, prefer unique current-file anchors over line numbers or stale pasted blocks.
 - Do not silently merge stale specs: if `old_string` is missing or ambiguous, re-read current source and ask whether to apply as-is, adapt, or skip.
-- Preserve UTF-8 BOM/no-BOM and LF/CRLF for existing multilingual/user-authored files; use UKit safe patch helpers internally when normal Edit/Write may normalize bytes.
+- Preserve UTF-8 BOM/no-BOM and LF/CRLF for existing multilingual/user-authored files.
+- Use `node .claude/ukit/index/safe-patch.mjs` internally when normal Edit/Write may normalize bytes or when anchor-based matching is needed.
 
 ## Team Workflow Safety
 
 - 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.
+
+## Adaptive Autonomy
+
+- `autonomy.level` in `.ukit/storage/config.json` controls how much UKit acts without asking first: `conservative` (ask more), `balanced` (default), `free-run` (auto-run more).
+- End users should not need to change this; maintainers may tune it per-project.
+
+## Session Start — OpenCode
+
+At the start of every OpenCode session, before working on the first task:
+1. Check `.claude/ukit/skill-router-state.json` — if `line` has route hints matching the current task, reuse them instead of re-routing from scratch.
+2. Note which skills are installed by scanning `.claude/skills/` (directory listing only); read the full SKILL.md only when a task triggers it.
+3. For every non-trivial task: run `/ukit-route <task summary>` immediately to get skill + context hints **before** writing any code.
+4. If the route result points to a skill, read that SKILL.md before acting — do not skip this step.
+5. If `.ukit/storage/config.json` has `router.enabled: true`, prefer the router's output over ad-hoc guessing.
 
 ## Environment Snapshot
 
@@ -123,8 +162,8 @@
 ## Skills
 
 - Canonical skills live in `.claude/skills/`.
-- Adapter mirrors may also exist, for example `.antigravity/skills/`.
-- OpenCode reads `AGENTS.md` plus the canonical `.claude/skills/` tree, so UKit keeps the OpenCode adapter lean and avoids a duplicate `.opencode/skills/` mirror.
+- Adapter mirrors may also exist, for example `.codex/skills/` → `.claude/skills/` (symlink) and `.antigravity/skills/`.
+- **OpenCode**: reads `AGENTS.md` at session start only — it does NOT auto-load `.claude/skills/`. The model must explicitly read the triggered SKILL.md (see Session Start section above).
 - If `opencode.json` ships `ukit-*` commands, treat them as internal helper entrypoints only and **never ask end users to run them**; humans should still only need `ukit install`.
 
 ## DuraOne Skill — Conditional Activation

package/templates/CLAUDE.md

@@ -4,7 +4,8 @@
 
 - Human-facing UKit workflow should collapse to one remembered command: `ukit install`.
 - After install, default to natural-language work inside Claude/Codex.
-- Optimize for output quality first, then speed, then token discipline.
+- **Quality first, then speed, then token discipline.**
+- **Never stop after read-only steps.** For implement/apply/fix requests, continue to actual Edit/Write and verification in the same turn.
 
 ## Fast Classification
 
@@ -12,6 +13,29 @@
 - **Simple**: keep scope tight; use the smallest useful context.
 - **Non-trivial / Risky**: read deeper, verify harder, and avoid shortcuts.
 
+## Execution Contract (mandatory)
+
+- 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 (Read/Grep/Glob/search).
+- If routed state says `pull-indexed-context`, treat it as internal continuation — 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 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.
+
+## Index-First Loop
+
+For any task that needs code context:
+
+1. Check if index is fresh (`.cache/index/` artifacts). If stale or missing, refresh:
+   - `node .claude/ukit/index/refresh-index.mjs`
+   - fallback: `node .claude/ukit/index/build-index.mjs`
+2. Query likely files:
+   - `node .claude/ukit/index/query-index.mjs "<error|symbol|path>"`
+3. For bug signatures:
+   - `node .claude/ukit/index/triage.mjs "<error signature>"`
+4. Open only the **top 1-3 suspect files first**, then widen if needed.
+
+For clearly non-code specialist lanes (docs-only, status, task queue), skip the source-code index.
+
 ## Automatic Skill Activation (mandatory)
 
 - End users should not need to know skill names.
@@ -42,24 +66,28 @@
 - **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.2 Shared Runtime
+## UKit v1.5.1 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.
 - Reuse `.ukit/storage/memory/` before asking users to restate decisions.
 - For non-trivial work, prefer `ukit memory recall "<current task>"` before widening doc reads.
-- Reusable cache/compact/output state lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, and `.ukit/storage/cache/output-history.json`.
+- Reusable cache/compact/output state lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, `.ukit/storage/cache/compact-pressure.json`, and `.ukit/storage/cache/output-history.json`.
+- Shared route memory lives in `.claude/ukit/skill-router-state.json`.
+- If shared route state already includes compact `previous-context` or `recent-output`, reuse those first.
 - If an older repo still has a visible `ukit/` runtime root, rerun `ukit install`; UKit should migrate the shared runtime into hidden `.ukit/` when safe.
 - Maintainers can inspect runtime state with `ukit status` and `ukit memory export`.
 - If runtime files are missing or corrupt, tell maintainers to rerun `ukit install`.
-
+- Threshold-based compact pressure is internal orchestration; do not expose it to users.
+- For Codex Desktop long sessions, UKit can use soft auto-compact handoffs. Default `compact.codexContext.compactTarget=150` means about 150 compact handoff lines (120-150 preferred, hard max 170), not 150 tokens.
 
 ## Safe Patch Protocol
 
 - Safe Patch is internal orchestration: normal users still only need `ukit install` and natural language.
 - For risky/shared/large edits, prefer unique current-file anchors over line numbers or stale pasted blocks.
 - Do not silently merge stale specs: if `old_string` is missing or ambiguous, re-read current source and ask whether to apply as-is, adapt, or skip.
-- Preserve UTF-8 BOM/no-BOM and LF/CRLF for existing multilingual/user-authored files; use UKit safe patch helpers internally when normal Edit/Write may normalize bytes.
+- Preserve UTF-8 BOM/no-BOM and LF/CRLF for existing multilingual/user-authored files.
+- Use `node .claude/ukit/index/safe-patch.mjs` internally when normal Edit/Write may normalize bytes or when anchor-based matching is needed.
 
 ## Context + Verification Budget
 
@@ -75,18 +103,19 @@
 
 - `docs/STATUS.md` captures compact current state, active work, debug threads, blockers, verification, and next candidates.
 - It is not source truth and must not replace source/index-first investigation.
-- For “what next?” / “continue” prompts without a concrete target, use `next-step` and show a freshness cue before relying on the status file.
+- For "what next?" / "continue" prompts without a concrete target, use `next-step` and show a freshness cue before relying on the status file.
 - For concrete debug/implementation/review prompts, keep the concrete workflow primary even if the user asks for an approach or next step.
 - After meaningful work, use `update-status`; skip trivial/no-state-change tasks and avoid transcript-style noise.
 - `docs/TASKS.md` is a local AI task queue: prefer `Ready for AI` when asked to pick queued work, and clean duplicates/prune `Done Recently` safely when reading/updating it.
 
-
 ## Small-Task Maintainer (internal)
 
 - UKit may route low-risk internal decisions to the `ukit-small-task-maintainer` subagent using `subagents.smallTaskModel` (default `unic-lite`).
 - Use it for safe/reversible UKit chores: dọn `docs/TASKS.md`, queued-task classification, fast-vs-slow/safe-vs-risky lane decisions, skill-routing/step-budget hints, agent context-budget decisions, compact/summary decisions, docs/status summarization, auto-triage, queue maintenance, and small workspace cleanup.
-- Run it as a sidecar/parallel lane only; do not block, replace, or slow the user task. Do not block the main AI flow: if the small-task lane sees security, risky/shared code, release/publish, data-loss, architecture, deep-reasoning risk, weak context, or quality risk, it hands back to the main model instead of asking the end user to decide.
-- This is optional internal orchestration config from `.ukit/storage/config.json`; never turn it into an end-user workflow. End users still only need `ukit install` and natural-language product work. Always preserve the CoDev priority: quality > safety > speed > token discipline. Keep Claude PreCompact/reinject and OpenCode native auto/prune compaction enabled. For Codex Desktop long sessions, `compact.codexContext.compactTarget` defaults to 150 compact handoff lines (120-150 preferred, hard max 170), decided internally by the small-task maintainer.
+- Run it as a sidecar/parallel lane only; do not block, replace, or slow the user task.
+- If the small-task lane sees security, risky/shared code, release/publish, data-loss, architecture, deep-reasoning risk, weak context, or quality risk, it hands back to the main model.
+- 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.
 
 ## Selective Subagent Policy (internal only)
 
@@ -97,10 +126,7 @@
 
 ## Adaptive Autonomy
 
-- `autonomy.level` in `.ukit/storage/config.json` controls how much UKit acts without asking first: `conservative` (ask more), `balanced` (default, current behavior), `free-run` (auto-run more).
-- `conservative`: do not auto-run fallback verification; ask before broad/risky escalation; suppress non-essential delegation (except explicit plan/batch execution and small-task maintainer).
-- `balanced`: default behavior unchanged — targeted verification auto-runs, broad risky asks confirmation, delegation follows existing thresholds.
-- `free-run`: auto-run fallback verification; remove broad verification confirmation for escalation-only; lower feature/debug delegation thresholds slightly.
+- `autonomy.level` in `.ukit/storage/config.json` controls how much UKit acts without asking first: `conservative` (ask more), `balanced` (default), `free-run` (auto-run more).
 - End users should not need to change this; maintainers may tune it per-project.
 
 ## Project Snapshot
@@ -114,9 +140,9 @@
 - 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 still says `pull-indexed-context`, treat it as an internal continuation step, not a stopping point.
 - 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.
+- 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/adapter-presets/opencode/opencode.template.json

@@ -1 +1 @@
-{"$schema":"https://opencode.ai/config.json","default_agent":"build","share":"disabled","compaction":{"auto":true,"prune":true,"reserved":10000},"watcher":{"ignore":[".git/**","node_modules/**",".cache/**",".claude/ukit/.ukit/**",".claude/ukit/permission-usage.json",".claude/ukit/permission-audit.log"]},"permission":{"doom_loop":"deny"},"command":{"ukit-route":{"description":"Internal shared UKit route.","agent":"build","template":"Run `node .claude/ukit/index/route-task.mjs \"<task>\" --adapter opencode`; reuse `.claude/ukit/skill-router-state.json`."},"ukit-context":{"description":"Internal UKit context.","agent":"build","template":"Run `node .claude/ukit/index/resolve-context.mjs \"<intent>\" [--target <file>]`."},"ukit-verify":{"description":"Internal UKit verify lane.","agent":"build","template":"Run `node .claude/ukit/index/verify-context.mjs \"<intent>\" [--target <file>]`."},"ukit-triage":{"description":"Internal UKit triage.","agent":"build","template":"Run `node .claude/ukit/index/triage.mjs \"<error>\"`."},"ukit-query":{"description":"Internal UKit query.","agent":"build","template":"Run `node .claude/ukit/index/query-index.mjs \"<error|symbol|path>\"`."},"ukit-index":{"description":"Internal UKit index.","agent":"build","template":"Run `node .claude/ukit/index/refresh-index.mjs` (fallback: `node .claude/ukit/index/build-index.mjs`)."}},"agent":{"build":{"description":"UKit coding agent; keep internal helpers hidden, users only need ukit install.","permission":{"edit":"allow","task":"allow","skill":"allow","bash":{"*":"ask","pwd":"allow","ls":"allow","ls *":"allow","find *":"allow","rg *":"allow","grep *":"allow","cat *":"allow","sed *":"allow","head *":"allow","tail *":"allow","wc *":"allow","git status":"allow","git status *":"allow","git diff":"allow","git diff *":"allow","git log":"allow","git log *":"allow","git show *":"allow","git grep *":"allow","git rev-parse *":"allow","node .claude/ukit/index/*":"allow","{{runtime.packageManager}} test":"allow","{{runtime.packageManager}} test *":"allow","{{runtime.packageManager}} lint":"allow","{{runtime.packageManager}} lint *":"allow","{{runtime.packageManager}} typecheck":"allow","{{runtime.packageManager}} typecheck *":"allow","{{runtime.packageManager}} build":"allow","{{runtime.packageManager}} build *":"allow","npm run test":"allow","npm run test *":"allow","npm run lint":"allow","npm run lint *":"allow","npm run typecheck":"allow","npm run typecheck *":"allow","npm run build":"allow","npm run build *":"allow","git commit":"ask","git commit *":"ask","git push":"ask","git push *":"ask","git clean":"deny","git clean *":"deny","git reset":"deny","git reset *":"deny","rm *":"deny"}}},"plan":{"permission":{"edit":"ask","bash":"ask"}}}}
+{"$schema":"https://opencode.ai/config.json","default_agent":"build","share":"disabled","compaction":{"auto":true,"prune":true,"reserved":10000},"watcher":{"ignore":[".git/**","node_modules/**",".cache/**",".ukit/**",".claude/ukit/permission-usage.json",".claude/ukit/permission-audit.log"]},"permission":{"doom_loop":"deny"},"command":{"ukit-route":{"description":"Internal shared UKit route. Run at the start of every non-trivial task to get skill and context hints before writing code.","agent":"build","template":"Run `node .claude/ukit/index/route-task.mjs \"<task>\" --adapter opencode`; reuse `.claude/ukit/skill-router-state.json`."},"ukit-context":{"description":"Internal UKit context.","agent":"build","template":"Run `node .claude/ukit/index/resolve-context.mjs \"<intent>\" [--target <file>]`."},"ukit-verify":{"description":"Internal UKit verify lane.","agent":"build","template":"Run `node .claude/ukit/index/verify-context.mjs \"<intent>\" [--target <file>]`."},"ukit-triage":{"description":"Internal UKit triage.","agent":"build","template":"Run `node .claude/ukit/index/triage.mjs \"<error>\"`."},"ukit-query":{"description":"Internal UKit query.","agent":"build","template":"Run `node .claude/ukit/index/query-index.mjs \"<error|symbol|path>\"`."},"ukit-index":{"description":"Internal UKit index.","agent":"build","template":"Run `node .claude/ukit/index/refresh-index.mjs` (fallback: `node .claude/ukit/index/build-index.mjs`)."}},"agent":{"build":{"description":"UKit build agent. Follow AGENTS.md. For every non-trivial task: run /ukit-route first, use index-first loop, activate matching skill, never claim done after read-only steps. Keep internal ukit-* helpers hidden; users only need ukit install.","permission":{"edit":"allow","task":"allow","skill":"allow","bash":{"*":"ask","pwd":"allow","ls":"allow","ls *":"allow","find *":"allow","rg *":"allow","grep *":"allow","cat *":"allow","sed *":"allow","head *":"allow","tail *":"allow","wc *":"allow","echo *":"allow","printf *":"allow","awk *":"allow","tr *":"allow","cut *":"allow","sort *":"allow","uniq *":"allow","diff *":"allow","jq *":"allow","stat *":"allow","file *":"allow","which *":"allow","date *":"allow","basename *":"allow","dirname *":"allow","realpath *":"allow","xargs *":"allow","mkdir *":"allow","touch *":"allow","cp *":"allow","vitest *":"allow","jest *":"allow","git status":"allow","git status *":"allow","git diff":"allow","git diff *":"allow","git log":"allow","git log *":"allow","git show *":"allow","git grep *":"allow","git rev-parse *":"allow","git branch *":"allow","git stash list":"allow","git ls-files *":"allow","git tag *":"allow","node .claude/ukit/index/*":"allow","node .claude/ukit/runtime/*":"allow","{{runtime.packageManager}} test":"allow","{{runtime.packageManager}} test *":"allow","{{runtime.packageManager}} lint":"allow","{{runtime.packageManager}} lint *":"allow","{{runtime.packageManager}} typecheck":"allow","{{runtime.packageManager}} typecheck *":"allow","{{runtime.packageManager}} build":"allow","{{runtime.packageManager}} build *":"allow","npm run test":"allow","npm run test *":"allow","npm run lint":"allow","npm run lint *":"allow","npm run typecheck":"allow","npm run typecheck *":"allow","npm run build":"allow","npm run build *":"allow","pnpm test":"allow","pnpm test *":"allow","pnpm lint":"allow","pnpm lint *":"allow","pnpm typecheck":"allow","pnpm typecheck *":"allow","pnpm build":"allow","pnpm build *":"allow","pnpm run test":"allow","pnpm run test *":"allow","pnpm run lint":"allow","pnpm run lint *":"allow","pnpm run typecheck":"allow","pnpm run typecheck *":"allow","pnpm run build":"allow","pnpm run build *":"allow","bun test":"allow","bun test *":"allow","bun run test":"allow","bun run test *":"allow","bun run lint":"allow","bun run lint *":"allow","bun run typecheck":"allow","bun run typecheck *":"allow","bun run build":"allow","bun run build *":"allow","git commit":"ask","git commit *":"ask","git push":"ask","git push *":"ask","git clean":"deny","git clean *":"deny","git reset":"deny","git reset *":"deny","rm *":"deny"}}},"plan":{"permission":{"edit":"ask","bash":"ask"}}}}

package/templates/ukit/README.md

@@ -1,6 +1,6 @@
 # UKit Shared Runtime
 
-This folder stores shared UKit runtime state for v1.4.4 features.
+This folder stores shared UKit runtime state for v1.5.0 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.4",
+  "version": "1.5.1",
   "agent": "claude-code",
   "autonomy": {
     "level": "balanced",
@@ -147,6 +147,7 @@
   "safePatch": {
     "enabled": true,
     "strictSharedRisk": true,
+    "advisoryOnly": false,
     "largeFileLineThreshold": 800,
     "largeFileByteThreshold": 200000,
     "backupEnabled": true,
@@ -365,6 +366,7 @@
     "safePatch": {
       "enabled": "Bật Safe Patch Protocol: UKit âm thầm chặn patch stale/ambiguous trên file rủi ro và giữ an toàn encoding khi helper nội bộ sửa file.",
       "strictSharedRisk": "Nếu true, file runtime/shared-risk như .claude/hooks hoặc .claude/ukit sẽ bị guard chặt hơn; người dùng vẫn không cần nhớ command mới.",
+      "advisoryOnly": "Nếu true (hoặc env UKIT_SAFE_PATCH_ADVISORY=1), guard chỉ in WARNING thay vì exit 2 — tránh Claude/Codex dừng giữa chừng chờ user 'continue'. Vẫn giữ message để model tự retry.",
       "largeFileLineThreshold": "Số dòng từ đó file được xem là lớn và cần anchor/spec guard kỹ hơn.",
       "largeFileByteThreshold": "Kích thước byte từ đó file được xem là lớn/rủi ro khi agent edit.",
       "backupEnabled": "Nếu true, UKit tạo rollback bytes dưới .ukit/storage/backups cho edit rủi ro.",