@ngockhoale/ukit 2.6.7 → 2.6.9

package/templates/docs/BUG_INDEX.md

@@ -10,3 +10,46 @@ Append-only recurring bug signatures.
 - Files changed:
 - Tests used:
 - Commit/PR:
+
+## Bugfix SOP
+
+### Objective
+Giảm thời gian fix bug bằng cách ưu tiên bằng chứng + index codebase trước khi đọc sâu docs/source.
+
+### Required Commands
+- `node .claude/ukit/index/build-index.mjs`
+- `node .claude/ukit/index/query-index.mjs "<error|symbol|path>"`
+- `node .claude/ukit/index/triage.mjs "<error signature>"`
+
+### Decision Tree
+1. Có repro command rõ ràng -> chạy triage index.
+2. Lane fast: mở tối đa 1-3 suspect files, patch nhỏ, verify test mục tiêu.
+3. Fail 2 vòng 15 phút liên tiếp -> chuyển lane deep.
+4. Lane deep: instrumentation + root-cause tracing trước khi sửa.
+
+### Hard Rules
+- Không sửa khi chưa có evidence (failing test / stack trace / logs).
+- Không refactor lớn trong bug ticket.
+- Verify tối thiểu: test fail ban đầu + test liên quan.
+
+## Intake Template
+
+- Title:
+- Priority: P0/P1/P2/P3
+- Repro command:
+- Expected vs Actual:
+- Error signature:
+- Stack trace excerpt:
+- Index triage output (`node .claude/ukit/index/triage.mjs "..."`):
+- Suspect files (top 3):
+- Lane (fast/deep):
+- Hypothesis:
+- Verify commands:
+
+## Metrics Baseline
+
+Track weekly:
+- MTTR P2/P3
+- First-pass fix rate
+- Avg files opened per simple bug
+- Fast-lane usage rate

package/templates/docs/BUG_METRICS.md

@@ -1,7 +1,3 @@
 # Bug Metrics
 
-Track weekly:
-- MTTR P2/P3
-- First-pass fix rate
-- Avg files opened per simple bug
-- Fast-lane usage rate
+Consolidated into `docs/BUG_INDEX.md` — see section "Metrics Baseline" (DOC-205).

package/templates/docs/BUG_TEMPLATE.md

@@ -1,13 +1,3 @@
 # Bug Intake Template
 
-- Title:
-- Priority: P0/P1/P2/P3
-- Repro command:
-- Expected vs Actual:
-- Error signature:
-- Stack trace excerpt:
-- Index triage output (`node .claude/ukit/index/triage.mjs "..."`):
-- Suspect files (top 3):
-- Lane (fast/deep):
-- Hypothesis:
-- Verify commands:
+Consolidated into `docs/BUG_INDEX.md` — see section "Intake Template" (DOC-205).

package/templates/docs/UKIT_INTERNALS.md

@@ -48,6 +48,10 @@ the root contract is the only carrier — keep both in sync with
   [--target <file>]` when routing is complex or ambiguous.
 - Prefer `node .claude/ukit/index/resolve-context.mjs ...` for indexed related-file context.
 - Prefer `node .claude/ukit/index/verify-context.mjs ...` for concrete verification lanes.
+- Context-layer docs are declared in `manifests/documentation.yaml` (`context_layers`) and
+  surfaced in the route summary line via the `docs=[...]` basename segment
+  (`routeSummary.contextDocs`; DOC-201). The routing-side copy is `CONTEXT_LAYER_DOCS` in
+  `src/index/taskRouting.js` / `route-task.mjs` — keep it in sync with the manifest.
 - Do not ask normal contributors to memorize `ukit doctor`, `ukit diff`, `ukit uninstall`,
   or `ukit index ...` unless they explicitly need maintainer/debug help.
 - If the workspace needs a refresh, prefer telling them to rerun `ukit install`.

package/templates/instructions/core.md

@@ -1,210 +1,157 @@
 ## Core Rule
 <!-- RULES: CORE-01 CORE-02 -->
-
-- Human-facing UKit workflow should collapse to one remembered command: `ukit install`.
+- Human-facing UKit workflow collapses to one remembered command: `ukit install`.
 - After install, default to natural-language work inside **Claude Code / Codex / OpenCode / omp**.
 - **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.
+- **Never stop after read-only steps** — implement/apply/fix requests continue to Edit/Write + verification in the same turn.
 
 ## Fast Classification
-
 <!-- RULE: CLS-01 -->
-- **Trivial** — typo, label, small rename, spacing, toggle flag, obvious config change.
-  - Act directly. No doc reads. No planning. No index. No agents.
+- **Trivial** — typo, label, small rename, spacing, toggle flag, obvious config change. Act directly. No doc reads, planning, index, or agents.
 <!-- RULE: CLS-02 -->
-- **Simple** — 1-2 files, clear scope, existing pattern.
-  - Handle directly. Pull only the smallest useful context via resolver or targeted read.
+- **Simple** — 1-2 files, clear scope, existing pattern. Handle directly; pull only the smallest useful context via resolver or targeted read.
 <!-- RULE: CLS-03 -->
-- **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.
+- **Non-trivial / Risky** — auth, security, migration, uninstall, shared runtime, race/flaky, data-loss. Read deeper, verify harder; index-first loop → skill activation → targeted verification.
 
 ## Execution Contract (mandatory)
-
 <!-- RULE: EXEC-01 -->
-- 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).
+- For explicit implement/apply/fix requests, **continue until the actual edit is made** or a real blocker is found — never stop after a read-only inspection step.
 <!-- RULE: EXEC-03 -->
-- If routed state 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 analysis.
+- Routed states like `pull-indexed-context` or `continuation required` — treat it as an internal continuation step, not a stopping point; finish the named milestone before widening reads.
 <!-- RULE: EXEC-02 -->
-- **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.
+- **Do NOT say "done"/"applied"/"fixed" after Read/Grep/analysis alone** — completion wording requires concrete Edit/Write evidence this turn, plus verification when scope is risky.
 <!-- RULE: EXEC-04 -->
-- **Every stop says why — no silent idle.** When a turn ends because only the user can act (login, approval, protected-file edit), open the reply with one line naming the exact action: `WAITING ON YOU: <command/action>`, and schedule a one-shot wakeup (~20-30 min) when the harness provides one so the session re-checks and auto-continues once the user has acted. An ended turn cannot observe external/auth changes by itself, so without that line (and the wakeup) the idle session looks identical to a stall. Any error — failed command, hook, test, publish — is reported verbatim in the same turn, never silently retried past the user.
+- **Every stop says why — no silent idle.** Turns ending on a user-only action open with `WAITING ON YOU: <command/action>` plus a one-shot wakeup (~20-30 min) when available — an ended turn cannot observe external changes, so without it idle looks identical to a stall. Report any error verbatim the same turn.
 
 ## Long-Run Continuity
 <!-- RULES: LONG-01 LONG-02 -->
-
 - Near token-cap: **LAND one thing** end-to-end (edit + verify, ≤3 tool calls), **DEFER** the rest into `docs/STATUS.md` or bounded `docs/AI_HANDOFF/` tasks, **DELEGATE** broad work to subagents. Only then compact.
-- After any compact or handoff: continue from the persisted disk state — never reread pre-compact context; delegate broad work, keep replies short.
-- A run ends only on completion evidence, a genuine blocker, or a user-only action — every such stop names its reason (Execution Contract). Detail: `docs/UKIT_INTERNALS.md`.
+- After any compact or handoff: continue from persisted disk state — never reread pre-compact context; delegate broad work, keep replies short.
+- A run ends only on completion evidence, a genuine blocker, or a user-only action — every stop names its reason. Detail: `docs/UKIT_INTERNALS.md`.
 
 ## Index-First Loop
-
-For any task that needs code context:
+For any task needing code context:
 
 <!-- RULE: IDX-01 -->
-1. Check if index is fresh (`.cache/index/` artifacts). If stale or missing, refresh (`node .claude/ukit/index/refresh-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>"`.
+1. Check the index is fresh (`.cache/index/`); if stale/missing, refresh via `node .claude/ukit/index/refresh-index.mjs`.
+2. Query files: `node .claude/ukit/index/query-index.mjs "<error|symbol|path>"`; bug signatures: `triage.mjs "<error signature>"`.
 <!-- RULE: IDX-02 -->
-4. Open only the **top 1-3 suspect files first**, then widen if needed. `query-index`/`resolve-context` print an `outline:` block — jump straight to `Read(file, offset=<line>)`.
+3. Open only the **top 1-3 suspect files first**, then widen if needed — the `outline:` block lets you jump straight to `Read(file, offset=<line>)`.
 <!-- RULE: IDX-03 -->
-   The outline locates code; it does not describe behaviour. **Any code you are about to change must still be read.**
-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.
+   The outline locates code; it does not describe behaviour — **any code you are about to change must still be read**.
+4. For analog/reuse patterns, check `resolve-context`. Non-code lanes (docs-only, status, task queue) skip the source-code index.
 
 ## Automatic Skill Activation (mandatory)
-
-- End users should not need to know skill names.
 <!-- RULE: SKILL-01 -->
-- On 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.
+- On every non-trivial task — and again after the first relevant tool calls — inspect installed project-local skills and **auto-activate the matching skill immediately**; end users should not need skill names. Match from prompt wording and tool/file evidence.
 <!-- RULES: SKILL-02 SKILL-03 -->
-- Use the smallest effective set, usually 1-2 skills; if evidence becomes more specific than the original prompt, upgrade the active skill choice immediately.
-- Prefer routed context and routed verification over ad-hoc broad reading; reuse `.claude/ukit/skill-router-state.json` when it already carries compact route memory.
+- Use the smallest effective set (usually 1-2 skills); if evidence sharpens, upgrade the active skill choice immediately.
+- Prefer routed context/verification over ad-hoc broad reading; reuse `.claude/ukit/skill-router-state.json` compact route memory.
 
 ### Common skill triggers
 
-- review / audit / diff / PR feedback → `.claude/skills/code-review/SKILL.md`
-- bug / error / crash / triage / failing path → `.claude/skills/debugging-toolkit/SKILL.md`
-- test / spec / coverage / fixture → `.claude/skills/testing-quality/SKILL.md`
-- docs / README / changelog / handoff / editing `docs/` / cleaning `docs/TASKS.md` → `.claude/skills/docs-quality/SKILL.md`
-- open-ended next step / project status / continue with no concrete target / choose queued task → `.claude/skills/next-step/SKILL.md`
-- explicit handoff / wrap up / update `docs/STATUS.md` → `.claude/skills/update-status/SKILL.md`
-- auth / security / token / permission / validation / risky shell-path-delete-db work → `.claude/skills/discover-security/SKILL.md`
-- stale workspace / reinstall / cleanup / maintenance → `.claude/skills/repo-maintenance/SKILL.md`
+- review / audit / diff / PR feedback → `code-review` · bug / error / crash / triage → `debugging-toolkit` · test / spec / coverage / fixture → `testing-quality`
+- docs / README / changelog / handoff / `docs/` edits → `docs-quality` (`.claude/skills/docs-quality/SKILL.md`) · open-ended / status / continue / queued task → `next-step` · wrap up / `docs/STATUS.md` update → `update-status`
+- auth / security / token / permission / risky work → `discover-security` · stale workspace / reinstall / cleanup → `repo-maintenance` (all under `.claude/skills/<name>/SKILL.md`)
 
 ## Internal Helper Policy
-
 <!-- RULES: HELP-01 HELP-02 -->
-- Prefer the internal index helpers (`node .claude/ukit/index/route-task.mjs`, `resolve-context.mjs`, `verify-context.mjs`) for routing, related-file context, and verification lanes.
+- Prefer the internal index helpers (`node .claude/ukit/index/route-task.mjs`, `resolve-context.mjs`, `verify-context.mjs`) for routing, related-file context, and verification.
 - **Do not ask normal contributors to run internal helper commands** or memorize maintainer commands (`ukit doctor`, `ukit diff`, `ukit uninstall`) — run them yourself.
 <!-- RULE: FALLBACK-01 -->
-- If the workspace needs a refresh or runtime files are missing/corrupt, tell maintainers to rerun `ukit install`. Detail: `docs/UKIT_INTERNALS.md`.
+- Missing/corrupt runtime files or stale workspace → tell maintainers to rerun `ukit install`. Detail: `docs/UKIT_INTERNALS.md`.
 
 ## Skill Quality (maintainer-only)
-
-- When editing a template skill/agent under `templates/.claude/`, read `.claude/skills/skill-quality/SKILL.md` before shipping the change.
+- When editing a template skill/agent under `templates/.claude/`, read `.claude/skills/skill-quality/SKILL.md` before shipping.
 
 ## UKit v{{ukit.version}} Shared Runtime
-
-- Shared runtime state lives in `.ukit/storage/`; `.ukit/storage/config.json` is the source of runtime toggles (compact, token pipeline, router, memory, validation, Safe Patch).
-- Reuse `.ukit/storage/memory/` and `ukit memory recall "<current task>"` before asking users to restate decisions or widening doc reads; maintainers can inspect state with `ukit status` / `ukit memory export`.
-- Shared route memory lives in `.claude/ukit/skill-router-state.json`; reuse compact `previous-context`/`recent-output` first.
-- If runtime files are missing/corrupt or an old visible `ukit/` root remains, rerun `ukit install`. Cache state (`.ukit/storage/cache/output-history.json`, tee/) + Codex handoff detail: `docs/UKIT_INTERNALS.md`.
+- Runtime state lives in `.ukit/storage/`; `.ukit/storage/config.json` holds runtime toggles (compact, token pipeline, router, memory, validation, Safe Patch).
+- Reuse `.ukit/storage/memory/` + `ukit memory recall "<current task>"` before asking users to restate decisions; inspect via `ukit status` / `ukit memory export`.
+- Route memory: `.claude/ukit/skill-router-state.json` — reuse compact `previous-context`/`recent-output` first. Cache state: `.ukit/storage/cache/output-history.json`, tee/. Missing/corrupt runtime or old `ukit/` root → rerun `ukit install`. Detail: `docs/UKIT_INTERNALS.md`.
 
 ## Prompt Caching
 <!-- RULES: CTX-01 CTX-02 CTX-03 CTX-04 CTX-05 CTX-06 CTX-07 CTX-08 CTX-09 CTX-10 -->
-
-- Full ruleset: `docs/PROMPT_CACHING.md` (read on demand; it is not loaded into every session).
+- Full ruleset: `docs/PROMPT_CACHING.md` (read on demand; not loaded every session).
 - CTX-01 deterministic segment bytes · CTX-02 keep roles and order · CTX-03 keep tool IDs and continuation state · CTX-04 no clock/random IDs in static blocks · CTX-05 compaction starts a new epoch · CTX-06 never change data to match a cache · CTX-07 no unconfirmed cache fields · CTX-08 tool-result reuse needs valid freshness · CTX-09 missing usage is unknown, not zero · CTX-10 never cut a required check to reduce calls.
 
 ## Safe Patch Protocol
 <!-- RULES: SAFE-02 SAFE-03 SAFE-01 -->
-
-- For risky/shared/large edits, prefer unique current-file anchors over line numbers or stale pasted blocks; 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.
-- Internal helper + detail: `docs/UKIT_INTERNALS.md` (`node .claude/ukit/index/safe-patch.mjs`).
+- Risky/shared/large edits: prefer unique current-file anchors over line numbers or stale pasted blocks; if `old_string` is missing/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. Helper: `node .claude/ukit/index/safe-patch.mjs`; detail: `docs/UKIT_INTERNALS.md`.
 
 ## Handoff Quality Gate — OPT-IN
 <!-- RULE: HAND-01 -->
-
 CHỈ kích hoạt khi task đi qua `docs/AI_HANDOFF/` (user nói "execute task TASK-xxx" hoặc target là `docs/AI_HANDOFF/tasks/*.md`). Daily prompt → KHÔNG đụng, flow cũ giữ nguyên.
 
-Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+Plan → Create Tasks → Implement+Test → Review+Test) + state machine + comment thread + self-report model. Config: `.ukit/storage/config.json` → `handoff.*`.
+Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+Plan → Create Tasks → Implement+Test → Review+Test) + state machine + self-report model. Config: `.ukit/storage/config.json` → `handoff.*`.
 
 ## Context + Verification Budget
 <!-- RULE: BUDGET-01 -->
-
-- **Trivial**: no docs, and no index query unless the file target is unclear.
-- **Simple**: `docs/MEMORY.md` only, plus resolver-selected files/tests.
-- **Non-trivial**: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
+- **Trivial**: no docs, no index query unless the file target is unclear. **Simple**: `docs/MEMORY.md` only + resolver-selected files/tests. **Non-trivial**: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
 <!-- RULES: BUDGET-02 BUDGET-03 -->
-- `docs/STATUS.md` for open-ended/continue prompts; `docs/TASKS.md` only for queued-task prompts; `docs/WORKLOG.md` recent entries only (archive overflow).
-- Follow routed verification policy: targeted first, widen only when risk/shared scope justifies it, ask before blanket broad runs.
+- `docs/STATUS.md` for open-ended/continue prompts; `docs/TASKS.md` only for queued-task prompts; `docs/WORKLOG.md` recent entries only (archive overflow). Verification: targeted first, widen only on risk/shared scope, ask before blanket broad runs.
 
 ## Living Status Workflow
 <!-- RULE: STATUS-01 -->
-
-- `docs/STATUS.md` captures compact current state; it is not source truth and must not replace source/index-first investigation.
-- For "what next?" / "continue" prompts, use `next-step` with a freshness cue; after meaningful work use `update-status`. `docs/TASKS.md` is the local AI task queue — prefer `Ready for AI`. Detail: `docs/UKIT_INTERNALS.md`.
+- `docs/STATUS.md` captures compact current state — not source truth, never replaces source/index-first investigation.
+- "What next?"/"continue" → `next-step` with a freshness cue; after meaningful work → `update-status`. `docs/TASKS.md` is the local AI task queue — prefer `Ready for AI`. Detail: `docs/UKIT_INTERNALS.md`.
 
 ## Small-Task Maintainer (internal)
 <!-- RULE: SUBAG-02 -->
-
 - The `ukit-small-task-maintainer` subagent (`subagents.smallTaskModel`, default `unic-lite`) handles safe/reversible UKit chores as a sidecar lane — never block or slow the user task; risky work hands back to the main model. Detail: `docs/UKIT_INTERNALS.md`.
 
 ## Post-Edit Sidecar Review (internal)
-
-- When routed state's `routeSummary.line` carries `review=code-reviewer(diff)`, launch the `code-reviewer` agent in the background (`smart` tier) **only after** write + verification evidence exists; findings are advisory — never block the already-reported completion. Detail: `docs/UKIT_INTERNALS.md`.
+- When routed state's `routeSummary.line` carries `review=code-reviewer(diff)`, launch `code-reviewer` in background (`smart` tier) **only after** write + verification evidence; findings advisory — never block the reported completion. Detail: `docs/UKIT_INTERNALS.md`.
 
 ## Selective Subagent Policy (internal only)
 <!-- RULE: SUBAG-01 -->
-
-- Keep direct execution as the default for trivial/simple work; delegate only when it meaningfully shrinks context or enables useful parallel progress (noisy side lanes, 3+ independent failures, batch plans, broad debug lanes).
-- Do not ask end users to name agents or remember agent commands.
+- Direct execution is default for trivial/simple work; delegate only on meaningful context shrink or parallel gains (noisy side lanes, 3+ independent failures, batch plans). Never ask end users to name agents or remember agent commands.
 
 ## Adaptive Autonomy
 <!-- RULE: AUTO-01 -->
-
-- `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), `vibecode` (run one prompt to a finished result; the completion gate stops only on completion evidence, a genuine blocker, or a dangerous-command decision).
-- End users should not need to change this; maintainers may tune it per-project.
+- `autonomy.level` in `.ukit/storage/config.json` controls how much UKit acts without asking: `conservative` (ask more), `balanced` (default), `free-run` (auto-run more), `vibecode` (one prompt to a finished result; the gate stops only on completion evidence, a genuine blocker, or a dangerous-command decision). End users should not need to change it.
 
 ## 3-Tier Model Routing
 <!-- RULES: TIER-01 TIER-02 -->
-
 **Internal orchestration only — end users still just use natural language. No new commands.**
 
 | Tier | Generic alias | Claude model | Typical tasks |
 |------|--------------|--------------|---------------|
 | lite | `unic-lite` | claude-haiku | Reads, git queries, bash summaries, small doc edits |
 | code | `unic-code` | claude-sonnet | Normal coding, local fixes, shared edits, builds, debugging, impact mapping |
-| smart | `unic-smart` | claude-opus | Release review/audit, and escalated deep reasoning after repeated failure |
+| smart | `unic-smart` | claude-opus | Release review/audit, escalated deep reasoning after repeated failure |
 
-- The main session model never changes mid-turn: a tier takes effect only when work is handed to an agent whose own definition binds that model (`model:` frontmatter in `.claude/agents/*.md`; `model:` `@lite`/`@code`/`@smart`/`@vision` in `.omp/agents/*.md` resolved via `modelRoles`).
-- Contract map: `tiny-fix` → lite · `local-fix`, `local-build`, `shared-edit`, `find-cause`, `map-impact` → code · `review-release` → smart.
-- Escalation: same file/symbol failing `debugLoopThreshold` (default 2) times in one session routes the next attempt one tier higher, capped at `smart`.
-- `unic-vision` is a capability lane, not a cost tier — unverified vision must never guess at image contents; route images to `ukit-vision-analyst`. Full harness table + gateway detection detail: `docs/UKIT_INTERNALS.md`.
+- A tier takes effect only when work is handed to an agent whose definition binds that model (`model:` frontmatter in `.claude/agents/*.md`; `model:` `@lite`/`@code`/`@smart`/`@vision` in `.omp/agents/*.md` via `modelRoles`) — the main session model never changes mid-turn.
+- Contract map: `tiny-fix` → lite · `local-fix`, `local-build`, `shared-edit`, `find-cause`, `map-impact` → code · `review-release` → smart. Escalation: same file/symbol failing `debugLoopThreshold` (default 2) times routes the next attempt one tier higher, capped at `smart`.
+- `unic-vision` is a capability lane, not a cost tier — unverified vision must never guess image contents; route images to `ukit-vision-analyst`. Harness table: `docs/UKIT_INTERNALS.md`.
 
 ## Skills
-
-- Canonical skills live in `.claude/skills/`; adapter mirrors may exist (`.codex/skills/` → symlink). **omp** reads `.claude/skills/` directly via its `claude` discovery provider.
+- Canonical skills live in `.claude/skills/`; adapter mirrors may exist (`.codex/skills/` → symlink). **omp** reads `.claude/skills/` via its `claude` discovery provider.
 - **OpenCode**: reads `AGENTS.md` at session start only — it does NOT auto-load skills; the model must explicitly read the triggered SKILL.md.
 - `ukit-*` commands in `opencode.json` are internal helper entrypoints — never ask end users to run them.
 
 ## Project Snapshot
-
 - Project: {{project.name}} | Root: {{project.root}}
 - Packs: {{project.stack}} | Frontend: {{stack.frontend}} | Backend API: {{stack.backendApi}} | PostgreSQL: {{stack.postgres}}
 - Package manager: {{runtime.packageManager}} | OS: {{runtime.os}} | Node: {{runtime.nodeVersion}} | Provider: {{providers.unic}}
 
 ## Working Rules
-
 - Keep scope tight, prefer the smallest correct change set, and reuse existing code.
 - Update `docs/WORKLOG.md` after significant work; if source contradicts docs, update docs immediately.
 - Use `{{runtime.packageManager}}`.
 
 ## DuraOne Skill — Conditional Activation
 <!-- RULE: DURA-01 -->
-
 DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skills/duraone/SKILL.md` tồn tại — khi active, luôn đọc SKILL.md + references trước khi code; khi không, dùng generic standards + index patterns. Chi tiết: `docs/UKIT_INTERNALS.md`.
 
 ## Completion Checklist
-
-- Requirements implemented
-- No unrelated changes
-- Verification executed and reported
-- Docs updated when source truth changed
+- Requirements implemented · No unrelated changes · Verification executed and reported · Docs updated when source truth changed.
 
 ## Handoff Fullstack Rules
 <!-- RULE: HAND-02 -->
-
 - `docs/AI_HANDOFF/RUN.md` là run cursor có thẩm quyền; `Phase:` ≠ `done`/`blocked` nghĩa là run còn sống — Stop gate từ chối stop và trả về `Next:` step.
 - Recap/checkpoint không bao giờ là completion — chỉ `HANDOFF FULLSTACK COMPLETE` (sau `Phase: done`) hoặc `HANDOFF FULLSTACK BLOCKED` (sau `Phase: blocked`) mới kết thúc run. Resume tự động mọi task chưa xong (current, legacy, pending, interrupted, recovery `-R<n>`).
 - Kết thúc cycle: docs sync → archive `docs/AI_HANDOFF/archive/cycle-NN/` → `Phase: done`. `handoff-clear` bắt buộc đóng RUN.md. Full rules: `docs/AI_HANDOFF/RULES.md`.
 
 ## Compact Instructions
-
 Khi compact giữa một handoff run: giữ lại goal, RUN.md path + phase hiện tại, task inventory, task đang làm, `Next:` step, blockers, verification evidence, commits, worktree/copy-back state, và quy tắc "compact không phải completion". Sau compact: đọc lại RUN.md + INDEX.md rồi chạy tiếp `Next:` ngay.

package/templates/ukit/storage/config.json

@@ -175,6 +175,41 @@
       "cap": "smart"
     }
   },
+  "codeIntel": {
+    "enabled": true,
+    "router": { "enabled": true, "defaultMode": "auto" },
+    "budgets": {
+      "peek": 500,
+      "targeted": 2000,
+      "impact": 3000,
+      "explore": 4000,
+      "deep_flow": 6000,
+      "analogy": 4000
+    },
+    "freshness": { "guardLevel": "L0", "autoRefresh": false, "incremental": true },
+    "retriever": {
+      "limit": 20,
+      "bm25": { "k1": 1.2, "b": 0.75 },
+      "merge": "rrf",
+      "rrfK": 60,
+      "weights": { "exact": 1.0, "symbol": 1.2, "bm25": 0.8, "semantic": 1.0, "vector": 0.6 }
+    },
+    "impact": { "defaultDepth": 2, "maxDepth": 4, "maxNodes": 200 },
+    "diagnostics": { "enabled": true, "timeoutMs": 8000 },
+    "providers": { "semantic": "null" },
+    "embedding": { "provider": "hashed", "dimensions": 256 },
+    "analogy": { "enabled": true, "limit": 5 },
+    "cochange": { "enabled": true, "maxCommits": 500, "minCount": 2, "timeoutMs": 5000 },
+    "summaries": { "enabled": true, "maxItems": 5 },
+    "graph": { "enabled": true, "store": "json" }
+  },
+  "memoryV2": {
+    "enabled": true,
+    "autoMigrate": true,
+    "episodeTtlDays": 90,
+    "promotion": { "episodeToRuleRequiresApproval": true },
+    "recall": { "maxRecords": 8 }
+  },
   "memory": {
     "enabled": true,
     "autoCapture": true,