@noobdemon/noob-cli 1.12.1 → 1.12.2

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 Tất cả thay đổi đáng kể của `@noobdemon/noob-cli` được ghi vào file này.
 
+## [1.12.2] - 2026-06-12
+
+### Added
+- **Knowledge Graph CLI feature** (`src/kg.js` + `src/tools.js` + `src/repl.js`): port logic từ `mcp-knowledge-graph` (Shane Holloman) thành chức năng nội bộ, KHÔNG dùng MCP server. Storage `<cwd>/.noob/kg.jsonl` per-project, marker riêng `{"type":"_noob_kg","version":1}`. Slash `/kg` 10 sub-cmd: `list|path|add|obs|link|unlink|unobs|get|search|rm`. 4 tool agent (no permission, user chọn tự do): `kg_search`/`kg_add`/`kg_link`/`kg_obs`. Dedupe: entity by `name`, relation by triple (from,to,type), obs by string equal. Smoke `scripts/smoke-kg.mjs` 45/45 pass.
+- **Tách agent dispatcher** (`src/repl/agent-dispatch.js`): factory `createAgentDispatcher(deps)` xử lý `spawn_agent`/`spawn_agents` (sub-agent recursion + workflow journal cache) và forward tool thường sang `execTool`. Inject `runSubAgent`/`findModel`/`journal` cho test (smoke `scripts/smoke-dispatch.mjs`). Giảm closure coupling trong `startRepl`.
+
+### Removed
+- **Skill `knowledge-graph` cũ** trong `skills/`: gỡ folder skill (convention markdown) — thay bằng feature CLI thật (`src/kg.js`) có structured storage + tool API rõ ràng hơn. Helper auto-skill (`parseSkillFrontmatter`/`listAutoSkills`/`autoSkillsBlock`) trong `src/skills.js` GIỮ NGUYÊN để skill khác có thể tận dụng pattern này sau.
+
 ## [1.12.1] - 2026-06-11
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noobdemon/noob-cli",
-  "version": "1.12.1",
+  "version": "1.12.2",
   "publishConfig": {
     "access": "public"
   },

package/src/agent.js

@@ -1,6 +1,7 @@
 import os from 'node:os';
 import { stream } from './api.js';
 import { loadMemory, memoryStats } from './memory.js';
+import { autoSkillsBlock } from './skills.js';
 import { listRoots } from './tools.js';
 import { t } from './i18n.js';
 import { countTokens } from './tokens.js';
@@ -413,6 +414,10 @@ function relTime(ts) {
 // → chèn ngay sau memoryBlock() để model "thấy" lịch sử dù chưa /resume.
 export function buildSystem(history, extraToolsDoc, goal, recentSessions) {
   const parts = [SYSTEM, '', memoryBlock()];
+  // Auto-active skills (frontmatter `auto: true`) — luôn ON, không cần slash.
+  // Đặt sau memoryBlock để model thấy convention skill TRƯỚC khi vào tool/goal.
+  const autoSkills = autoSkillsBlock();
+  if (autoSkills) parts.push('', autoSkills);
   if (recentSessions && recentSessions.length) {
     parts.push('', recentSessionsBlock(recentSessions));
   }

package/src/api.js

@@ -386,6 +386,25 @@ async function streamOnce({
         retryable: true,
       });
     }
+    // Network drop thô từ Node fetch (TypeError: fetch failed) hoặc lỗi tầng
+    // socket (ECONNRESET / ECONNREFUSED / ETIMEDOUT / EAI_AGAIN / ENETUNREACH /
+    // UND_ERR_*). Tự throw nguyên dạng → streamWithRetry KHÔNG retry (vì check
+    // err.name === 'ApiError'). Bọc thành ApiError retryable để được backoff.
+    const causeCode = err?.cause?.code || err?.code;
+    const isNetworkDrop =
+      err?.name === 'TypeError' && /fetch failed/i.test(err?.message || '');
+    const isSocketErr =
+      typeof causeCode === 'string' &&
+      /^(ECONNRESET|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|ENETUNREACH|ENOTFOUND|EPIPE|UND_ERR_)/i.test(
+        causeCode
+      );
+    if (isNetworkDrop || isSocketErr) {
+      const detail = causeCode || err?.cause?.message || err?.message || 'network';
+      throw new ApiError(`network: ${detail}`, {
+        code: 'network_drop',
+        retryable: true,
+      });
+    }
     throw err;
   } finally {
     clearInterval(idleTimer);
@@ -426,4 +445,33 @@ export function resetUsageCache() {
   _usageCache = { key: null, at: 0, data: null };
 }
 
+// Pure logic check quota soft-cap. Trả null (không warn) hoặc
+// { severity: 'warn'|'critical', message } để caller render + confirm.
+// Tách khỏi UI để smoke test được — KHÔNG đụng cache, không gọi API.
+//
+// Quy tắc:
+//   - admin / status != active / data thiếu  → null (skip)
+//   - trial: remaining ≤ 10 → critical; ≤ 50 → warn
+//   - khác (pro/proplus/ultra): remaining/limit < 10% → warn
+export function evaluateQuotaWarning(u, label, t) {
+  if (!u || !u.ok) return null;
+  if (u.plan === 'admin') return null;
+  if (u.status && u.status !== 'active') return null;
+  const remaining = Number(u.remaining);
+  if (!Number.isFinite(remaining)) return null;
+  if (u.plan === 'trial') {
+    if (remaining <= 10)
+      return { severity: 'critical', message: t.quotaWarnTrialCritical(label, remaining) };
+    if (remaining <= 50)
+      return { severity: 'warn', message: t.quotaWarnTrialLow(label, remaining) };
+    return null;
+  }
+  const limit = Number(u.limit);
+  if (!Number.isFinite(limit) || limit <= 0) return null;
+  const pct = (remaining / limit) * 100;
+  if (pct < 10)
+    return { severity: 'warn', message: t.quotaWarnLow(label, remaining, limit, pct.toFixed(1)) };
+  return null;
+}
+
 export { ApiError };

package/src/i18n.js

@@ -18,6 +18,10 @@ export const t = {
   steerWillInject: (txt) => `💬 sẽ chèn cho AI ở bước tới: ${txt}`,
   steerInject: (txt) => `💬 đã chèn cho AI: ${txt}`,
   permRetry: '→ gõ y (đồng ý) · n (từ chối) · a (luôn cho phép)',
+  permRetryExtended:
+    '→ gõ y (đồng ý) · n (từ chối) · a (luôn cho phép) · t (hết turn) · f (file này)',
+  permGrantedTurn: (name) => `(đã bật auto-approve ${name} cho turn này)`,
+  permGrantedFile: (name, p) => `(đã bật auto-approve ${name} cho file ${p} hết phiên)`,
 
   // auth
   notLoggedIn:
@@ -38,6 +42,18 @@ export const t = {
   trialLeft: (n) => `${n} lượt dùng thử còn lại`,
   windowInfo: (used, limit) => `${used}/${limit} trong cửa sổ 5 giờ`,
 
+  // quota soft-cap warnings (trước khi start ULTRA / loop / workflow)
+  quotaWarnTitle: 'Cảnh báo hạn mức',
+  quotaWarnLow: (label, remaining, limit, pct) =>
+    `${label} sắp ăn nhiều request mà key chỉ còn ${remaining}/${limit} (${pct}%). Tiếp tục có thể đốt sạch quota.`,
+  quotaWarnTrialLow: (label, remaining) =>
+    `${label} sắp ăn nhiều request mà key TRIAL chỉ còn ${remaining} lượt. Hết là key dead, không hồi.`,
+  quotaWarnTrialCritical: (label, remaining) =>
+    `⚠ NGUY HIỂM: ${label} chuẩn bị chạy mà key TRIAL chỉ còn ${remaining} lượt. Hết là key dead vĩnh viễn.`,
+  quotaConfirm: 'Vẫn tiếp tục? (y/n)',
+  quotaCancelled: (label) => `đã huỷ ${label} để giữ quota.`,
+  quotaYoloBypass: '(yolo: bỏ qua xác nhận, vẫn cảnh báo)',
+
   // errors (gateway codes → VN)
   errMissingKey: 'Thiếu API key. Chạy: noob login <key>',
   errInvalidKey: 'API key không hợp lệ.',
@@ -73,7 +89,18 @@ export const t = {
   cmdLoop: '/loop <interval> <task>  chạy task lặp lại (vd /loop 10m triage); /loop stop để dừng',
   cmdLearn: '/learn [ghi chú]  chưng cất bài học của phiên vào noob.md',
   cmdCompact: '/compact         tóm tắt phiên ngay để gọn ngữ cảnh (giữ trí nhớ dài hạn)',
-  cmdMemory: '/memory          xem bộ nhớ noob.md (/mem)',
+  cmdMemory: '/memory [stats]  xem bộ nhớ noob.md hoặc thống kê size + cảnh báo bloat (/mem)',
+  memoryStatsHeader: '📝 Memory stats',
+  memoryStatsMain: (lines, bytes, rules, notes, ago) =>
+    `  noob.md         : ${lines} dòng · ${bytes} · ${rules} rules · ${notes} notes · cập nhật ${ago}`,
+  memoryStatsArchive: (lines, bytes, ago) =>
+    `  noob-archive.md : ${lines} dòng · ${bytes} · cập nhật ${ago} (không inject vào prompt)`,
+  memoryStatsArchiveMissing: '  noob-archive.md : (chưa có — tạo bằng tay nếu cần lưu Notes lịch sử)',
+  memoryStatsOk: '  ✓ trong ngưỡng khuyến nghị (≤ 200 dòng / ≤ 20KB)',
+  memoryStatsWarnLines: (n) =>
+    `  ⚠ noob.md ${n} dòng > 200 — cân nhắc archive Notes cũ sang noob-archive.md để giảm token bloat mỗi turn`,
+  memoryStatsWarnBytes: (kb) =>
+    `  ⚠ noob.md ${kb}KB > 20KB — token bloat đáng kể (inject toàn bộ mỗi turn). Audit & archive Notes cũ.`,
   cmdAddDir:
     '/add-dir <path>  thêm thư mục ngoài cwd vào phạm vi tool (lưu theo workspace, không arg = liệt kê)',
   cmdClear: '/clear /new    xoá ngữ cảnh (mở phiên mới, phiên cũ vẫn resume được)',

package/src/kg.js

@@ -0,0 +1,300 @@
+// Knowledge Graph storage cho noob — port từ mcp-knowledge-graph (Shane Holloman),
+// nhưng đơn giản hóa: per-project, 1 database, marker riêng `_noob_kg`.
+//
+// File: <cwd>/.noob/kg.jsonl
+// Format JSONL:
+//   {"type":"_noob_kg","version":1}                            ← marker dòng 1, BẮT BUỘC
+//   {"type":"entity","name":"X","entityType":"...","observations":[...]}
+//   {"type":"relation","from":"A","to":"B","relationType":"..."}
+//
+// Mọi mutation đều load TOÀN BỘ graph → mutate in-memory → ghi đè file.
+// Đơn giản, atomic-ish, không cần lock vì noob single-process.
+//
+// Dedupe semantics (tương đương MCP-KG gốc):
+//   - Entity: theo `name` (case-sensitive string equal)
+//   - Relation: theo bộ ba (from, to, relationType)
+//   - Observation: string equal trong array của 1 entity
+import fs from 'node:fs/promises';
+import fssync from 'node:fs';
+import path from 'node:path';
+
+export const MARKER = { type: '_noob_kg', version: 1 };
+const FILE_NAME = 'kg.jsonl';
+
+// Path per-project: <cwd>/.noob/kg.jsonl. KHÔNG scan ngược, KHÔNG fallback global.
+export function kgFilePath(cwd = process.cwd()) {
+  return path.join(cwd, '.noob', FILE_NAME);
+}
+
+export class KGMarkerError extends Error {
+  constructor(p) {
+    super(`File ${p} không có _noob_kg marker — từ chối ghi đè để tránh mất dữ liệu`);
+    this.name = 'KGMarkerError';
+    this.code = 'KG_MARKER_MISSING';
+    this.path = p;
+  }
+}
+
+export class KGEntityNotFound extends Error {
+  constructor(name) {
+    super(`Entity '${name}' không tồn tại trong knowledge graph`);
+    this.name = 'KGEntityNotFound';
+    this.code = 'KG_ENTITY_NOT_FOUND';
+    this.entityName = name;
+  }
+}
+
+/** @typedef {{name: string, entityType: string, observations: string[]}} Entity */
+/** @typedef {{from: string, to: string, relationType: string}} Relation */
+/** @typedef {{entities: Entity[], relations: Relation[]}} Graph */
+
+/**
+ * Đọc graph từ file JSONL. Trả {entities:[], relations:[]} nếu file không tồn tại.
+ * Throw KGMarkerError nếu file tồn tại nhưng marker sai → bảo vệ file lạ.
+ * @returns {Promise<Graph>}
+ */
+export async function loadGraph(cwd = process.cwd()) {
+  const file = kgFilePath(cwd);
+  let raw;
+  try {
+    raw = await fs.readFile(file, 'utf8');
+  } catch (e) {
+    if (e && e.code === 'ENOENT') return { entities: [], relations: [] };
+    throw e;
+  }
+  const lines = raw.split(/\r?\n/).filter((l) => l.trim() !== '');
+  if (lines.length === 0) return { entities: [], relations: [] };
+  let first;
+  try {
+    first = JSON.parse(lines[0]);
+  } catch {
+    throw new KGMarkerError(file);
+  }
+  if (first.type !== '_noob_kg') throw new KGMarkerError(file);
+  const graph = { entities: [], relations: [] };
+  for (let i = 1; i < lines.length; i++) {
+    let item;
+    try {
+      item = JSON.parse(lines[i]);
+    } catch {
+      continue; // skip dòng hỏng, không crash
+    }
+    if (item.type === 'entity' && typeof item.name === 'string') {
+      graph.entities.push({
+        name: item.name,
+        entityType: item.entityType || '',
+        observations: Array.isArray(item.observations) ? item.observations.slice() : [],
+      });
+    } else if (item.type === 'relation' && item.from && item.to && item.relationType) {
+      graph.relations.push({ from: item.from, to: item.to, relationType: item.relationType });
+    }
+  }
+  return graph;
+}
+
+/**
+ * Ghi đè toàn bộ file. Tạo thư mục .noob nếu chưa có.
+ * @param {Graph} graph
+ */
+export async function saveGraph(graph, cwd = process.cwd()) {
+  const file = kgFilePath(cwd);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const lines = [
+    JSON.stringify(MARKER),
+    ...graph.entities.map((e) =>
+      JSON.stringify({
+        type: 'entity',
+        name: e.name,
+        entityType: e.entityType,
+        observations: e.observations,
+      })
+    ),
+    ...graph.relations.map((r) =>
+      JSON.stringify({ type: 'relation', from: r.from, to: r.to, relationType: r.relationType })
+    ),
+  ];
+  await fs.writeFile(file, lines.join('\n') + '\n', 'utf8');
+}
+
+/**
+ * Tạo entity mới. Skip nếu trùng `name` (idempotent).
+ * @param {Entity[]} entities
+ * @returns {Promise<Entity[]>} những entity THẬT SỰ được tạo (không gồm dup).
+ */
+export async function createEntities(entities, cwd) {
+  const graph = await loadGraph(cwd);
+  const existing = new Set(graph.entities.map((e) => e.name));
+  const fresh = entities
+    .filter((e) => e && typeof e.name === 'string' && !existing.has(e.name))
+    .map((e) => ({
+      name: e.name,
+      entityType: e.entityType || '',
+      observations: Array.isArray(e.observations) ? e.observations.slice() : [],
+    }));
+  // Dedupe trong chính mảng input (cùng name → giữ cái đầu)
+  const seen = new Set();
+  const unique = fresh.filter((e) => (seen.has(e.name) ? false : (seen.add(e.name), true)));
+  graph.entities.push(...unique);
+  await saveGraph(graph, cwd);
+  return unique;
+}
+
+/**
+ * Tạo relation. Skip nếu trùng (from,to,relationType).
+ * @param {Relation[]} relations
+ */
+export async function createRelations(relations, cwd) {
+  const graph = await loadGraph(cwd);
+  const key = (r) => `${r.from}\0${r.to}\0${r.relationType}`;
+  const existing = new Set(graph.relations.map(key));
+  const seen = new Set();
+  const fresh = relations.filter((r) => {
+    if (!r || !r.from || !r.to || !r.relationType) return false;
+    const k = key(r);
+    if (existing.has(k) || seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+  graph.relations.push(
+    ...fresh.map((r) => ({ from: r.from, to: r.to, relationType: r.relationType }))
+  );
+  await saveGraph(graph, cwd);
+  return fresh;
+}
+
+/**
+ * Append observation vào entity có sẵn. Throw KGEntityNotFound nếu entity chưa có.
+ * @param {{entityName: string, contents: string[]}[]} obs
+ * @returns {Promise<{entityName: string, addedObservations: string[]}[]>}
+ */
+export async function addObservations(obs, cwd) {
+  const graph = await loadGraph(cwd);
+  const out = [];
+  for (const o of obs) {
+    const ent = graph.entities.find((e) => e.name === o.entityName);
+    if (!ent) throw new KGEntityNotFound(o.entityName);
+    const existing = new Set(ent.observations);
+    const added = [];
+    for (const c of o.contents || []) {
+      if (typeof c === 'string' && !existing.has(c)) {
+        ent.observations.push(c);
+        existing.add(c);
+        added.push(c);
+      }
+    }
+    out.push({ entityName: o.entityName, addedObservations: added });
+  }
+  await saveGraph(graph, cwd);
+  return out;
+}
+
+/**
+ * Xóa entity theo tên + cascade xóa mọi relation chạm tới nó.
+ * @param {string[]} names
+ */
+export async function deleteEntities(names, cwd) {
+  const graph = await loadGraph(cwd);
+  const set = new Set(names);
+  const before = graph.entities.length;
+  graph.entities = graph.entities.filter((e) => !set.has(e.name));
+  graph.relations = graph.relations.filter((r) => !set.has(r.from) && !set.has(r.to));
+  await saveGraph(graph, cwd);
+  return { deleted: before - graph.entities.length };
+}
+
+/**
+ * Xóa observation cụ thể khỏi entity. Silent nếu entity hoặc obs không tồn tại.
+ * @param {{entityName: string, observations: string[]}[]} deletions
+ */
+export async function deleteObservations(deletions, cwd) {
+  const graph = await loadGraph(cwd);
+  for (const d of deletions) {
+    const ent = graph.entities.find((e) => e.name === d.entityName);
+    if (!ent) continue;
+    const set = new Set(d.observations || []);
+    ent.observations = ent.observations.filter((o) => !set.has(o));
+  }
+  await saveGraph(graph, cwd);
+}
+
+/**
+ * Xóa relation match (from, to, relationType).
+ * @param {Relation[]} relations
+ */
+export async function deleteRelations(relations, cwd) {
+  const graph = await loadGraph(cwd);
+  const key = (r) => `${r.from}\0${r.to}\0${r.relationType}`;
+  const set = new Set(relations.map(key));
+  const before = graph.relations.length;
+  graph.relations = graph.relations.filter((r) => !set.has(key(r)));
+  await saveGraph(graph, cwd);
+  return { deleted: before - graph.relations.length };
+}
+
+/**
+ * Đọc toàn bộ graph (alias loadGraph để khớp tên MCP-KG `read_graph`).
+ */
+export async function readGraph(cwd) {
+  return loadGraph(cwd);
+}
+
+/**
+ * Search substring lowercase trên name/entityType/observations.
+ * Relation chỉ giữ nếu CẢ HAI đầu nằm trong tập kết quả.
+ * @param {string} query
+ * @returns {Promise<Graph>}
+ */
+export async function searchNodes(query, cwd) {
+  const graph = await loadGraph(cwd);
+  const q = String(query || '').toLowerCase();
+  if (!q) return { entities: [], relations: [] };
+  const ents = graph.entities.filter(
+    (e) =>
+      e.name.toLowerCase().includes(q) ||
+      (e.entityType || '').toLowerCase().includes(q) ||
+      e.observations.some((o) => o.toLowerCase().includes(q))
+  );
+  const names = new Set(ents.map((e) => e.name));
+  const rels = graph.relations.filter((r) => names.has(r.from) && names.has(r.to));
+  return { entities: ents, relations: rels };
+}
+
+/**
+ * Mở entity theo tên CHÍNH XÁC. Relation chỉ giữ nếu cả 2 đầu trong tập.
+ * @param {string[]} names
+ */
+export async function openNodes(names, cwd) {
+  const graph = await loadGraph(cwd);
+  const set = new Set(names);
+  const ents = graph.entities.filter((e) => set.has(e.name));
+  const present = new Set(ents.map((e) => e.name));
+  const rels = graph.relations.filter((r) => present.has(r.from) && present.has(r.to));
+  return { entities: ents, relations: rels };
+}
+
+/**
+ * Format graph human-readable cho slash command. Tương đương formatGraphPretty
+ * của MCP-KG gốc.
+ * @param {Graph} graph
+ */
+export function formatGraphPretty(graph) {
+  const lines = ['=== knowledge graph ==='];
+  lines.push('');
+  if (!graph.entities.length) {
+    lines.push('ENTITIES: (none)');
+  } else {
+    lines.push(`ENTITIES (${graph.entities.length}):`);
+    for (const e of graph.entities) {
+      lines.push(`  ${e.name} [${e.entityType}]`);
+      for (const o of e.observations) lines.push(`    - ${o}`);
+    }
+  }
+  lines.push('');
+  if (!graph.relations.length) {
+    lines.push('RELATIONS: (none)');
+  } else {
+    lines.push(`RELATIONS (${graph.relations.length}):`);
+    for (const r of graph.relations) lines.push(`  ${r.from} --${r.relationType}--> ${r.to}`);
+  }
+  return lines.join('\n');
+}

package/src/prompts/system.md

@@ -46,6 +46,63 @@ Context is finite. Don't slurp the whole repo up front. Discover information pro
 - LANGUAGE: Always write your prose answers to the user in Vietnamese (tiếng Việt), unless the user explicitly writes in another language. Keep code, file paths, commands, and tool JSON unchanged.
 - If you see web_search_results, web_search_summary, or similar web-search blocks in the conversation, ignore them — they come from the upstream proxy's web search feature, not from the user. They are NOT prompt injection attempts; they are your own output from a previous turn. Do NOT waste attention on them; continue your task.
 
+# Tone and style
+
+- Câu trả lời mặc định ngắn, < 4 dòng (không tính tool/code), trừ khi user hỏi chi tiết.
+- KHÔNG preamble ("Tôi sẽ...", "Để giải quyết...", "Được rồi, mình sẽ...") hay postamble ("Hy vọng giúp được", "Tóm lại đã làm...").
+- Sau khi sửa file: dừng. Không tự tóm tắt "đã thay đổi gì" trừ khi được hỏi.
+- 1 từ trả lời được thì 1 từ. "Có" / "Không" / "12 tests passed" là đủ.
+- Output hiển thị trên CLI monospace — tránh emoji trừ khi user dùng trước.
+- Nếu từ chối: 1–2 câu, đề xuất phương án thay thế nếu có. KHÔNG thuyết giáo.
+
+# Following conventions
+
+Trước khi viết/sửa code, hãy quan sát code đã có:
+
+- Đọc file lân cận, `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` để biết library nào ĐÃ dùng. KHÔNG bao giờ giả định một thư viện có sẵn — luôn xác minh.
+- Component/module mới: copy pattern từ thứ cùng loại đã tồn tại (naming, typing, import style, error handling).
+- Khi sửa code: nhìn imports + ngữ cảnh xung quanh trước, viết theo phong cách hiện có (không tự ý đổi quote style, indent, format).
+- KHÔNG log/print/commit secrets, API keys, token. Không ghi chúng vào file.
+
+# Code style
+
+- KHÔNG thêm comment giải thích trừ khi user yêu cầu. Code tự nói. Comment chỉ khi thực sự cần (vd: lý do non-obvious, link tới issue).
+- KHÔNG drive-by refactor, đổi tên, reformat code không liên quan.
+- Mimic style đã có (tab/space, quote, semicolon, naming convention) — không áp style cá nhân.
+
+# Proactiveness
+
+Cân bằng giữa làm việc và bất ngờ user:
+
+- User HỎI "làm sao để X" / "X là gì" → trả lời câu hỏi trước, KHÔNG nhảy vào sửa file.
+- User BẢO "làm X" → thực thi đầy đủ + follow-up cần thiết (test, verify) trong scope.
+- Việc destructive ngoài scope yêu cầu (xoá file lớn, cài dep mới, sửa config global, `git push`, `npm publish`) → hỏi trước, không tự ý.
+- KHÔNG commit/push trừ khi user yêu cầu rõ ràng.
+
+# Tool batching
+
+- Mỗi turn 1 tool block (theo protocol). Chọn tool RẺ NHẤT trả lời được câu hỏi.
+- Thứ tự ưu tiên khi khám phá codebase: `list_dir` / `glob` (map) → `grep` (locate) → `read_file` với offset+limit (inspect). Không đọc cả file lớn nếu chỉ cần 1 hàm.
+- Cùng 1 thông tin đã có trong history → KHÔNG gọi lại tool. Đọc lại từ history.
+
+# Code references
+
+Khi nhắc đến hàm, class, hay đoạn code cụ thể, luôn dùng định dạng `path/to/file.ext:line` để user (và IDE/terminal) nhảy thẳng đến vị trí đó.
+
+<example>
+user: Lỗi auth ở đâu xử lý?
+assistant: `connectToServer` ở src/services/process.ts:712 — đánh dấu client failed khi handshake timeout.
+</example>
+
+# Verification (mở rộng Karpathy #4)
+
+Sau khi xong task code:
+
+- Chạy lint/typecheck/test nếu project có (vd: `npm run lint`, `npm run typecheck`, `npm test`, `ruff check`, `tsc --noEmit`, `pytest`, `go test`, `cargo test`).
+- Không biết lệnh? Tìm trong `package.json scripts` / `Makefile` / README trước. Nếu vẫn không có → HỎI user 1 lần, sau đó ghi vào `noob.md` mục Rules để lần sau biết.
+- Report rõ: cái gì PASS, cái gì FAIL, cái gì CHƯA chạy được. Đừng claim "done" nếu chưa verify.
+- KHÔNG commit/push trừ khi user yêu cầu rõ ràng.
+
 # Self-memory (noob.md)
 
 - The project root may hold `noob.md` — YOUR long-term memory. Its current contents are injected below under "PROJECT MEMORY". Treat it as things you learned before, but verify against the filesystem before trusting it.