@ngockhoale/ukit 2.7.10 → 2.7.12

package/templates/AGENTS.md

@@ -3,142 +3,126 @@
 
 ## Core Rule
 <!-- RULES: CORE-01 CORE-02 -->
-- Human-facing UKit workflow collapses to one remembered command: `ukit install`.
-- After install, default to natural-language work inside **Claude Code / Codex / omp**.
+- One command: `ukit install`; then work in natural language inside **Claude Code / Codex / omp**.
 - **Quality first, then speed, then token discipline.**
-- **Never stop after read-only steps** — implement/apply/fix requests continue to Edit/Write + verification in the same turn.
+- **Never stop after read-only steps** — implement/apply/fix continues to Edit/Write + verification same turn.
 
 ## Fast Classification
 <!-- RULE: CLS-01 -->
-- **Trivial** — typo, label, small rename, spacing, toggle flag, obvious config change. Act directly. No doc reads, planning, index, or agents.
+- **Trivial** — typo, label, rename, spacing, flag, obvious config. Act directly; no docs/index/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. Act directly; smallest useful context only.
 <!-- RULE: CLS-03 -->
-- **Non-trivial / Risky** — auth, security, migration, uninstall, shared runtime, race/flaky, data-loss. Read deeper, verify harder; index-first loop → skill activation → targeted verification.
+- **Non-trivial / Risky** — auth, security, migration, uninstall, shared runtime, race/flaky, data-loss. Index-first → skill → 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 — never stop after a read-only inspection step.
+- Implement/apply/fix: continue until the actual edit is made or a real blocker — never stop after read-only inspection.
 <!-- RULE: EXEC-03 -->
-- 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.
+- Routed states (`pull-indexed-context`, `continuation required`): treat it as an internal continuation step, not a stopping point; finish the named milestone first.
 <!-- RULE: EXEC-02 -->
-- **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.
+- **No "done"/"applied"/"fixed" after Read/Grep/analysis alone** — needs concrete Edit/Write evidence this turn, plus verification when risky.
 <!-- RULE: EXEC-04 -->
-- **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.
+- **Every stop says why — no silent idle.** User-only-action stops open with `WAITING ON YOU: <command/action>` + one-shot wakeup (~20-30 min) when available; report errors verbatim.
 
 ## Stall & Wait Reporting
 <!-- RULE: STALL-01 -->
-- Announce long waits as they happen: `Waiting for API response / tool result — will keep retrying; check your network/API provider if this persists`. Surface any API/tool error **verbatim** in the same turn, and name network/API as the suspect on long stalls — **never blame UKit**. This guidance makes the model's side of a wait visible; it cannot detect a stall inside the host's own request loop.
+- Announce long waits: `Waiting for API response / tool result — will keep retrying; check your network/API provider if this persists`. Surface errors verbatim; suspect network/API — **never blame UKit**.
 <!-- RULE: STALL-02 -->
-- Every stop still says why (Execution Contract EXEC-04) — the stall rules above extend it, they do not replace it.
+- Stall rules extend EXEC-04 (every stop says why); they do not replace it.
 <!-- RULE: STALL-03 -->
-- **Conditional workaround only:** fall back to one tool call per assistant message ONLY when malformed/concatenated tool-input errors are observed or the harness version is known-affected — otherwise keep using legitimate parallel calls; serializing healthy hosts contradicts batching guidance.
+- **Conditional workaround only:** one tool call per assistant message only when malformed/concatenated tool-input errors are observed or the harness is known-affected — healthy hosts keep parallel calls.
 
 ## 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 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`.
+- Near token-cap: **LAND one thing** end-to-end (edit + verify, ≤3 tool calls), **DEFER** the rest to `docs/STATUS.md` or bounded `docs/AI_HANDOFF/` tasks, **DELEGATE** broad work to subagents. Then compact.
+- After compact/handoff: continue from persisted disk state — never reread pre-compact context; delegate broadly, keep replies short.
+- A run ends only on completion evidence, a genuine blocker, or a user-only action — every stop names its reason.
 
 ## Index-First Loop
-For any task needing code context:
-
 <!-- RULE: IDX-01 -->
-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>"`.
+1. Check the index is fresh (`.cache/index/`); stale/missing → `node .claude/ukit/index/refresh-index.mjs`. Query: `query-index.mjs "<error|symbol|path>"`; bugs: `triage.mjs "<error>"`.
 <!-- RULE: IDX-02 -->
-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>)`.
+2. Open only the **top 1-3 suspect files first**, then widen — `outline:` jumps 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**.
-4. For analog/reuse patterns, check `resolve-context`. Non-code lanes (docs-only, status, task queue) skip the source-code index.
+   The outline locates code, not behaviour — **code you are about to change must still be read**. Analog/reuse → `resolve-context`; non-code lanes skip.
 
 ## Automatic Skill Activation (mandatory)
 <!-- 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**; end users should not need skill names. Match from prompt wording and tool/file evidence.
+- On every non-trivial task — and again after the first relevant tool calls — **auto-activate the matching skill immediately**; users never name skills. Match from prompt wording and tool/file evidence.
 <!-- RULES: SKILL-02 SKILL-03 -->
-- 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.
+- Smallest effective set (1-2 skills); upgrade as evidence sharpens. Prefer routed context/verification over broad reading; reuse `.claude/ukit/skill-router-state.json` route memory.
 
 ### Common skill triggers
-
-- 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`)
+- review/audit/diff → `code-review` · bug/error/crash → `debugging-toolkit` · test/coverage → `testing-quality` · docs/README/`docs/` → `docs-quality` (`.claude/skills/docs-quality/SKILL.md`) · open-ended/continue → `next-step` · wrap-up/`docs/STATUS.md` → `update-status` · auth/security/risky → `discover-security` · stale workspace/cleanup → `repo-maintenance`
 
 ## 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.
+- Prefer the internal index helpers (`node .claude/ukit/index/route-task.mjs`, `resolve-context.mjs`, `verify-context.mjs`) for routing, context, 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 -->
-- Missing/corrupt runtime files or stale workspace → tell maintainers to rerun `ukit install`. Detail: `docs/UKIT_INTERNALS.md`.
+- Missing/corrupt runtime or stale workspace → rerun `ukit install`.
 
 ## Skill Quality (maintainer-only)
-- When editing a template skill/agent under `templates/.claude/`, read `.claude/skills/skill-quality/SKILL.md` before shipping.
+- Editing `templates/.claude/` skills/agents → read `.claude/skills/skill-quality/SKILL.md` first.
 
 ## UKit v{{ukit.version}} Shared Runtime
-- 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; `ukit memory learn` surfaces pending proposals, `ukit memory promote` writes approved rules to MEMORY.md, `ukit memory episode` records session episodes; 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`, `retriever-lanes.jsonl`, `tee/`. Lifecycle hooks all degrade to exit 0 (SessionEnd `session-episode.sh` auto-writes episodes; full map: `docs/UKIT_INTERNALS.md`). Missing/corrupt runtime or old `ukit/` root → rerun `ukit install`. Detail: `docs/UKIT_INTERNALS.md`.
-
+- Runtime state: `.ukit/storage/`; `config.json` holds toggles (compact, token pipeline, router, memory, validation, Safe Patch). `ukit memory recall "<task>"` before asking users to restate decisions; `learn`/`promote`/`episode` manage memory; inspect via `ukit status` / `ukit memory export`. Route memory: `.claude/ukit/skill-router-state.json` (`previous-context`/`recent-output` first); cache: `.ukit/storage/cache/output-history.json` + `retriever-lanes.jsonl` + `tee/`. Hooks degrade to exit 0; missing/corrupt runtime → rerun `ukit install`.
 ## 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; 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.
+- Full ruleset: `docs/PROMPT_CACHING.md` (read on demand).
 
 ## Safe Patch Protocol
 <!-- RULES: SAFE-02 SAFE-03 SAFE-01 -->
-- 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`.
+- Risky/shared/large edits: prefer unique current-file anchors over line numbers or stale pasted blocks; missing/ambiguous `old_string` → re-read source, then apply, adapt, or skip.
+- Preserve UTF-8 BOM/no-BOM and LF/CRLF on existing files. Helper: `node .claude/ukit/index/safe-patch.mjs`.
 
 ## 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 + self-report model. Config: `.ukit/storage/config.json` → `handoff.*`.
+Chỉ active khi task đi qua `docs/AI_HANDOFF/` ("execute task TASK-xxx" hoặc `docs/AI_HANDOFF/tasks/*.md`); daily prompt giữ flow cũ. Khi active: đọc `docs/AI_HANDOFF/RULES.md` (4 phase + state machine + self-report). Config: `.ukit/storage/config.json` → `handoff.*`.
 
 ## Context + Verification Budget
 <!-- RULE: BUDGET-01 -->
-- **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`.
+- **Trivial**: no docs, no index query unless the target is unclear. **Simple**: `docs/MEMORY.md` + resolver-selected files/tests. **Non-trivial**: + `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). Verification: targeted first, widen only on risk/shared scope, ask before blanket broad runs.
+- `docs/STATUS.md` for open-ended/continue; `docs/TASKS.md` only for queued-task prompts; `docs/WORKLOG.md` recent entries only. Verification: targeted first, widen on risk/shared scope, ask before broad runs.
 
 ## Living Status Workflow
 <!-- RULE: STATUS-01 -->
-- `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`.
+- `docs/STATUS.md` = compact current state — not source truth, never replaces index-first investigation.
+- "What next?"/"continue" → `next-step`; after meaningful work → `update-status`. `docs/TASKS.md` = local AI task queue — prefer `Ready for AI`.
 
 ## Subagent Lanes (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`.
-- 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`.
+- `ukit-small-task-maintainer` (`subagents.smallTaskModel`, default `unic-lite`) = sidecar lane for safe/reversible UKit chores — never block the user task; risky work hands back.
 <!-- RULE: SUBAG-01 -->
-- 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.
+- Direct execution is default for trivial/simple work; delegate only on real context shrink or parallel gains. Never ask users to name agents or agent commands.
 
 ## Adaptive Autonomy
 <!-- RULE: AUTO-01 -->
-- `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.
+- `autonomy.level` in `.ukit/storage/config.json`: `conservative` | `balanced` (default) | `free-run` | `vibecode` (one prompt to a finished result; stops only on completion evidence, a genuine blocker, or a dangerous-command decision).
 
 ## Unattended Completion Loop
 <!-- RULE: UNATTENDED-01 -->
-- Under `orchestration.permissionMode: unattended` there is no human in the loop — the loop is UNDERSTAND → PLAN → IMPLEMENT → VERIFY → FIX → REVERIFY → COMPLETE. A turn ends only on COMPLETE evidence, a real external blocker, or a deny decision.
+- `orchestration.permissionMode: unattended` = no human in the loop — UNDERSTAND → PLAN → IMPLEMENT → VERIFY → FIX → REVERIFY → COMPLETE. A turn ends only on COMPLETE evidence, a real external blocker, or a deny.
 <!-- RULE: UNATTENDED-02 -->
-- `maxAttemptsPerFailure: 5` per failing verification, `maxRecoveryStrategies: 3` distinct fix strategies before reassessing — retry the same edit, fix the cause differently, then reduce scope/approach; do not loop one strategy.
+- `maxAttemptsPerFailure: 2`, `maxRecoveryStrategies: 2` distinct fix strategies before reassessing — retry the same edit, then fix the cause differently; never loop one strategy.
 <!-- RULE: UNATTENDED-03 -->
-- BLOCKED only on true external blockers: missing credentials, dead service, unreachable network/API. Test failures, lint errors, review findings, and ambiguity are NOT blockers — they feed FIX.
+- BLOCKED only on true external blockers: missing credentials, dead service, unreachable network/API. Test failures, lint errors, review findings, ambiguity are NOT blockers — feed FIX.
 <!-- RULE: UNATTENDED-04 -->
-- A deny (hook/gate/permission) never becomes a question: pick the next safer alternative that satisfies the intent and record the substitution. Never emit "do you want me to…" — decide and proceed.
+- A deny (hook/gate/permission) never becomes a question: pick the next safer alternative satisfying the intent, record the substitution. Never emit "do you want me to…" — decide and proceed.
 
 ## 3-Tier Model Routing
 <!-- RULES: TIER-01 TIER-02 -->
-**Internal orchestration only — end users still just use natural language. No new commands.**
+**Internal orchestration only — end users still 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, escalated deep reasoning after repeated failure |
+| Tier | Alias | Claude model |
+|------|-------|--------------|
+| lite | `unic-lite` | claude-haiku |
+| code | `unic-code` | claude-sonnet |
+| smart | `unic-smart` | claude-opus |
 
-- A tier takes effect only when work is handed to an agent whose definition binds that model (`model:` frontmatter in `.claude/agents/*.md`; `model:` `@smol`/`@default`/`@slow`/`@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`.
+- A tier binds only via an agent's `model:` field (`.claude/agents/*.md`; `.omp/agents/*.md` `@smol`/`@default`/`@slow`/`@vision` via `modelRoles`) — the 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` (2) → one tier up, cap `smart`. `unic-vision` = capability lane (not cost) — never guess images; route to `ukit-vision-analyst`.
 
 ## Project Owner Instructions — Codex
 
@@ -149,31 +133,25 @@ If it is missing or unreadable, state that limitation and continue with the
 remaining project instructions.
 <!-- RULE: OWN-01 -->
 ## Skills
-- Canonical skills live in `.claude/skills/`; adapter mirrors may exist (`.codex/skills/` → symlink). **omp** reads `.claude/skills/` via its `claude` discovery provider.
+- Canonical skills: `.claude/skills/`; adapter mirrors may exist (`.codex/skills/` → symlink). **omp** reads `.claude/skills/` via its `claude` provider.
 
 ## 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}}
+- Project: {{project.name}} | Root: {{project.root}} | Packs: {{project.stack}} | PM: {{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}}`.
+- Keep scope tight; smallest correct change set; reuse existing code. Update `docs/WORKLOG.md` after significant work; source contradicts docs → update docs. 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`.
+DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skills/duraone/SKILL.md` tồn tại — khi active, đọc SKILL.md + references trước khi code; khi không, dùng generic standards + index patterns.
 
 ## Completion Checklist
-- Requirements implemented · No unrelated changes · Verification executed and reported · Docs updated when source truth changed.
+- Requirements implemented · No unrelated changes · Verification executed + 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`.
+- `docs/AI_HANDOFF/RUN.md` là run cursor có thẩm quyền; `Phase:` ≠ `done`/`blocked` = run còn sống — Stop gate từ chối stop, trả về `Next:`. Chỉ `HANDOFF FULLSTACK COMPLETE`/`BLOCKED` kết thúc run — recap/checkpoint không phải completion; resume tự động mọi task chưa xong. Kết thúc cycle: docs sync → archive `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.
+Compact giữa handoff run: giữ goal, RUN.md path + phase, task inventory + task đang làm, `Next:` step, blockers, verification evidence, commits, worktree/copy-back state, "compact không phải completion". Sau compact: đọc lại RUN.md + INDEX.md rồi chạy `Next:`.
 {{codegraphSection}}

package/templates/CLAUDE.md

@@ -3,169 +3,147 @@
 
 ## Core Rule
 <!-- RULES: CORE-01 CORE-02 -->
-- Human-facing UKit workflow collapses to one remembered command: `ukit install`.
-- After install, default to natural-language work inside **Claude Code / Codex / omp**.
+- One command: `ukit install`; then work in natural language inside **Claude Code / Codex / omp**.
 - **Quality first, then speed, then token discipline.**
-- **Never stop after read-only steps** — implement/apply/fix requests continue to Edit/Write + verification in the same turn.
+- **Never stop after read-only steps** — implement/apply/fix continues to Edit/Write + verification same turn.
 
 ## Fast Classification
 <!-- RULE: CLS-01 -->
-- **Trivial** — typo, label, small rename, spacing, toggle flag, obvious config change. Act directly. No doc reads, planning, index, or agents.
+- **Trivial** — typo, label, rename, spacing, flag, obvious config. Act directly; no docs/index/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. Act directly; smallest useful context only.
 <!-- RULE: CLS-03 -->
-- **Non-trivial / Risky** — auth, security, migration, uninstall, shared runtime, race/flaky, data-loss. Read deeper, verify harder; index-first loop → skill activation → targeted verification.
+- **Non-trivial / Risky** — auth, security, migration, uninstall, shared runtime, race/flaky, data-loss. Index-first → skill → 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 — never stop after a read-only inspection step.
+- Implement/apply/fix: continue until the actual edit is made or a real blocker — never stop after read-only inspection.
 <!-- RULE: EXEC-03 -->
-- 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.
+- Routed states (`pull-indexed-context`, `continuation required`): treat it as an internal continuation step, not a stopping point; finish the named milestone first.
 <!-- RULE: EXEC-02 -->
-- **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.
+- **No "done"/"applied"/"fixed" after Read/Grep/analysis alone** — needs concrete Edit/Write evidence this turn, plus verification when risky.
 <!-- RULE: EXEC-04 -->
-- **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.
+- **Every stop says why — no silent idle.** User-only-action stops open with `WAITING ON YOU: <command/action>` + one-shot wakeup (~20-30 min) when available; report errors verbatim.
 
 ## Stall & Wait Reporting
 <!-- RULE: STALL-01 -->
-- Announce long waits as they happen: `Waiting for API response / tool result — will keep retrying; check your network/API provider if this persists`. Surface any API/tool error **verbatim** in the same turn, and name network/API as the suspect on long stalls — **never blame UKit**. This guidance makes the model's side of a wait visible; it cannot detect a stall inside the host's own request loop.
+- Announce long waits: `Waiting for API response / tool result — will keep retrying; check your network/API provider if this persists`. Surface errors verbatim; suspect network/API — **never blame UKit**.
 <!-- RULE: STALL-02 -->
-- Every stop still says why (Execution Contract EXEC-04) — the stall rules above extend it, they do not replace it.
+- Stall rules extend EXEC-04 (every stop says why); they do not replace it.
 <!-- RULE: STALL-03 -->
-- **Conditional workaround only:** fall back to one tool call per assistant message ONLY when malformed/concatenated tool-input errors are observed or the harness version is known-affected — otherwise keep using legitimate parallel calls; serializing healthy hosts contradicts batching guidance.
+- **Conditional workaround only:** one tool call per assistant message only when malformed/concatenated tool-input errors are observed or the harness is known-affected — healthy hosts keep parallel calls.
 
 ## 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 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`.
+- Near token-cap: **LAND one thing** end-to-end (edit + verify, ≤3 tool calls), **DEFER** the rest to `docs/STATUS.md` or bounded `docs/AI_HANDOFF/` tasks, **DELEGATE** broad work to subagents. Then compact.
+- After compact/handoff: continue from persisted disk state — never reread pre-compact context; delegate broadly, keep replies short.
+- A run ends only on completion evidence, a genuine blocker, or a user-only action — every stop names its reason.
 
 ## Index-First Loop
-For any task needing code context:
-
 <!-- RULE: IDX-01 -->
-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>"`.
+1. Check the index is fresh (`.cache/index/`); stale/missing → `node .claude/ukit/index/refresh-index.mjs`. Query: `query-index.mjs "<error|symbol|path>"`; bugs: `triage.mjs "<error>"`.
 <!-- RULE: IDX-02 -->
-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>)`.
+2. Open only the **top 1-3 suspect files first**, then widen — `outline:` jumps 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**.
-4. For analog/reuse patterns, check `resolve-context`. Non-code lanes (docs-only, status, task queue) skip the source-code index.
+   The outline locates code, not behaviour — **code you are about to change must still be read**. Analog/reuse → `resolve-context`; non-code lanes skip.
 
 ## Automatic Skill Activation (mandatory)
 <!-- 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**; end users should not need skill names. Match from prompt wording and tool/file evidence.
+- On every non-trivial task — and again after the first relevant tool calls — **auto-activate the matching skill immediately**; users never name skills. Match from prompt wording and tool/file evidence.
 <!-- RULES: SKILL-02 SKILL-03 -->
-- 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.
+- Smallest effective set (1-2 skills); upgrade as evidence sharpens. Prefer routed context/verification over broad reading; reuse `.claude/ukit/skill-router-state.json` route memory.
 
 ### Common skill triggers
-
-- 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`)
+- review/audit/diff → `code-review` · bug/error/crash → `debugging-toolkit` · test/coverage → `testing-quality` · docs/README/`docs/` → `docs-quality` (`.claude/skills/docs-quality/SKILL.md`) · open-ended/continue → `next-step` · wrap-up/`docs/STATUS.md` → `update-status` · auth/security/risky → `discover-security` · stale workspace/cleanup → `repo-maintenance`
 
 ## 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.
+- Prefer the internal index helpers (`node .claude/ukit/index/route-task.mjs`, `resolve-context.mjs`, `verify-context.mjs`) for routing, context, 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 -->
-- Missing/corrupt runtime files or stale workspace → tell maintainers to rerun `ukit install`. Detail: `docs/UKIT_INTERNALS.md`.
+- Missing/corrupt runtime or stale workspace → rerun `ukit install`.
 
 ## Skill Quality (maintainer-only)
-- When editing a template skill/agent under `templates/.claude/`, read `.claude/skills/skill-quality/SKILL.md` before shipping.
+- Editing `templates/.claude/` skills/agents → read `.claude/skills/skill-quality/SKILL.md` first.
 
 ## UKit v{{ukit.version}} Shared Runtime
-- 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; `ukit memory learn` surfaces pending proposals, `ukit memory promote` writes approved rules to MEMORY.md, `ukit memory episode` records session episodes; 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`, `retriever-lanes.jsonl`, `tee/`. Lifecycle hooks all degrade to exit 0 (SessionEnd `session-episode.sh` auto-writes episodes; full map: `docs/UKIT_INTERNALS.md`). Missing/corrupt runtime or old `ukit/` root → rerun `ukit install`. Detail: `docs/UKIT_INTERNALS.md`.
-
+- Runtime state: `.ukit/storage/`; `config.json` holds toggles (compact, token pipeline, router, memory, validation, Safe Patch). `ukit memory recall "<task>"` before asking users to restate decisions; `learn`/`promote`/`episode` manage memory; inspect via `ukit status` / `ukit memory export`. Route memory: `.claude/ukit/skill-router-state.json` (`previous-context`/`recent-output` first); cache: `.ukit/storage/cache/output-history.json` + `retriever-lanes.jsonl` + `tee/`. Hooks degrade to exit 0; missing/corrupt runtime → rerun `ukit install`.
 ## 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; 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.
+- Full ruleset: `docs/PROMPT_CACHING.md` (read on demand).
 
 ## Safe Patch Protocol
 <!-- RULES: SAFE-02 SAFE-03 SAFE-01 -->
-- 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`.
+- Risky/shared/large edits: prefer unique current-file anchors over line numbers or stale pasted blocks; missing/ambiguous `old_string` → re-read source, then apply, adapt, or skip.
+- Preserve UTF-8 BOM/no-BOM and LF/CRLF on existing files. Helper: `node .claude/ukit/index/safe-patch.mjs`.
 
 ## 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 + self-report model. Config: `.ukit/storage/config.json` → `handoff.*`.
+Chỉ active khi task đi qua `docs/AI_HANDOFF/` ("execute task TASK-xxx" hoặc `docs/AI_HANDOFF/tasks/*.md`); daily prompt giữ flow cũ. Khi active: đọc `docs/AI_HANDOFF/RULES.md` (4 phase + state machine + self-report). Config: `.ukit/storage/config.json` → `handoff.*`.
 
 ## Context + Verification Budget
 <!-- RULE: BUDGET-01 -->
-- **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`.
+- **Trivial**: no docs, no index query unless the target is unclear. **Simple**: `docs/MEMORY.md` + resolver-selected files/tests. **Non-trivial**: + `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). Verification: targeted first, widen only on risk/shared scope, ask before blanket broad runs.
+- `docs/STATUS.md` for open-ended/continue; `docs/TASKS.md` only for queued-task prompts; `docs/WORKLOG.md` recent entries only. Verification: targeted first, widen on risk/shared scope, ask before broad runs.
 
 ## Living Status Workflow
 <!-- RULE: STATUS-01 -->
-- `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`.
+- `docs/STATUS.md` = compact current state — not source truth, never replaces index-first investigation.
+- "What next?"/"continue" → `next-step`; after meaningful work → `update-status`. `docs/TASKS.md` = local AI task queue — prefer `Ready for AI`.
 
 ## Subagent Lanes (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`.
-- 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`.
+- `ukit-small-task-maintainer` (`subagents.smallTaskModel`, default `unic-lite`) = sidecar lane for safe/reversible UKit chores — never block the user task; risky work hands back.
 <!-- RULE: SUBAG-01 -->
-- 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.
+- Direct execution is default for trivial/simple work; delegate only on real context shrink or parallel gains. Never ask users to name agents or agent commands.
 
 ## Adaptive Autonomy
 <!-- RULE: AUTO-01 -->
-- `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.
+- `autonomy.level` in `.ukit/storage/config.json`: `conservative` | `balanced` (default) | `free-run` | `vibecode` (one prompt to a finished result; stops only on completion evidence, a genuine blocker, or a dangerous-command decision).
 
 ## Unattended Completion Loop
 <!-- RULE: UNATTENDED-01 -->
-- Under `orchestration.permissionMode: unattended` there is no human in the loop — the loop is UNDERSTAND → PLAN → IMPLEMENT → VERIFY → FIX → REVERIFY → COMPLETE. A turn ends only on COMPLETE evidence, a real external blocker, or a deny decision.
+- `orchestration.permissionMode: unattended` = no human in the loop — UNDERSTAND → PLAN → IMPLEMENT → VERIFY → FIX → REVERIFY → COMPLETE. A turn ends only on COMPLETE evidence, a real external blocker, or a deny.
 <!-- RULE: UNATTENDED-02 -->
-- `maxAttemptsPerFailure: 5` per failing verification, `maxRecoveryStrategies: 3` distinct fix strategies before reassessing — retry the same edit, fix the cause differently, then reduce scope/approach; do not loop one strategy.
+- `maxAttemptsPerFailure: 2`, `maxRecoveryStrategies: 2` distinct fix strategies before reassessing — retry the same edit, then fix the cause differently; never loop one strategy.
 <!-- RULE: UNATTENDED-03 -->
-- BLOCKED only on true external blockers: missing credentials, dead service, unreachable network/API. Test failures, lint errors, review findings, and ambiguity are NOT blockers — they feed FIX.
+- BLOCKED only on true external blockers: missing credentials, dead service, unreachable network/API. Test failures, lint errors, review findings, ambiguity are NOT blockers — feed FIX.
 <!-- RULE: UNATTENDED-04 -->
-- A deny (hook/gate/permission) never becomes a question: pick the next safer alternative that satisfies the intent and record the substitution. Never emit "do you want me to…" — decide and proceed.
+- A deny (hook/gate/permission) never becomes a question: pick the next safer alternative satisfying the intent, record the substitution. Never emit "do you want me to…" — decide and proceed.
 
 ## 3-Tier Model Routing
 <!-- RULES: TIER-01 TIER-02 -->
-**Internal orchestration only — end users still just use natural language. No new commands.**
+**Internal orchestration only — end users still 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, escalated deep reasoning after repeated failure |
+| Tier | Alias | Claude model |
+|------|-------|--------------|
+| lite | `unic-lite` | claude-haiku |
+| code | `unic-code` | claude-sonnet |
+| smart | `unic-smart` | claude-opus |
 
-- A tier takes effect only when work is handed to an agent whose definition binds that model (`model:` frontmatter in `.claude/agents/*.md`; `model:` `@smol`/`@default`/`@slow`/`@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`.
+- A tier binds only via an agent's `model:` field (`.claude/agents/*.md`; `.omp/agents/*.md` `@smol`/`@default`/`@slow`/`@vision` via `modelRoles`) — the 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` (2) → one tier up, cap `smart`. `unic-vision` = capability lane (not cost) — never guess images; route to `ukit-vision-analyst`.
 
 ## Skills
-- Canonical skills live in `.claude/skills/`; adapter mirrors may exist (`.codex/skills/` → symlink). **omp** reads `.claude/skills/` via its `claude` discovery provider.
+- Canonical skills: `.claude/skills/`; adapter mirrors may exist (`.codex/skills/` → symlink). **omp** reads `.claude/skills/` via its `claude` provider.
 
 ## 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}}
+- Project: {{project.name}} | Root: {{project.root}} | Packs: {{project.stack}} | PM: {{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}}`.
+- Keep scope tight; smallest correct change set; reuse existing code. Update `docs/WORKLOG.md` after significant work; source contradicts docs → update docs. 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`.
+DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skills/duraone/SKILL.md` tồn tại — khi active, đọc SKILL.md + references trước khi code; khi không, dùng generic standards + index patterns.
 
 ## Completion Checklist
-- Requirements implemented · No unrelated changes · Verification executed and reported · Docs updated when source truth changed.
+- Requirements implemented · No unrelated changes · Verification executed + 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`.
+- `docs/AI_HANDOFF/RUN.md` là run cursor có thẩm quyền; `Phase:` ≠ `done`/`blocked` = run còn sống — Stop gate từ chối stop, trả về `Next:`. Chỉ `HANDOFF FULLSTACK COMPLETE`/`BLOCKED` kết thúc run — recap/checkpoint không phải completion; resume tự động mọi task chưa xong. Kết thúc cycle: docs sync → archive `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.
+Compact giữa handoff run: giữ goal, RUN.md path + phase, task inventory + task đang làm, `Next:` step, blockers, verification evidence, commits, worktree/copy-back state, "compact không phải completion". Sau compact: đọc lại RUN.md + INDEX.md rồi chạy `Next:`.
 {{codegraphSection}}