@starci/hfs 1.0.0

package/runtime/modules/kernel/failure-codes.yaml

@@ -0,0 +1,169 @@
+HFS_CANON_PIN_DRIFT:
+  title: "Dependency version differs from the canon pin"
+  title_vi: "Phiên bản phụ thuộc lệch khỏi bản đã ghim"
+  meaning_vi: "Một phụ thuộc trong package.json không đúng phiên bản chính xác mà knowledge/hfs/canon-pins.yaml ghim cho cả họ kho; mọi gói @starci đều được cài từ npm registry đúng phiên bản đã ghim (không dùng file:)."
+  causes_vi:
+    - "Phiên bản viết dạng khoảng (^, ~) thay vì phiên bản chính xác"
+    - "Một workspace giữ phiên bản cũ của cùng phụ thuộc"
+    - "Một gói @starci khai báo dạng file: hoặc khoảng phiên bản thay vì phiên bản chính xác trên registry"
+  nextStep_vi: "Đặt phụ thuộc về đúng phiên bản chính xác ghi trong knowledge/hfs/canon-pins.yaml rồi cài lại từ npm registry. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra; không cần ai can thiệp thêm."
+  owner: op-retry
+  kind: check-finding
+
+HFS_DECLARATION_INVALID:
+  title: "hfs.json missing or invalid"
+  title_vi: "hfs.json thiếu hoặc sai định dạng"
+  meaning_vi: "Kho mã không có tệp hfs.json hợp lệ nên không thể biết nó theo chuẩn HFS nào, có những ứng dụng nào và bật những ô tuỳ chọn nào."
+  causes_vi:
+    - "Thiếu tệp hfs.json ở gốc kho, hoặc tệp không đọc được như JSON"
+    - "Loại ứng dụng không có trong bảng kê của HFS, ví dụ một loại ứng dụng do kho tự đặt"
+    - "optionalSlots ghi một ô không phải loại tuỳ chọn, hoặc ghi một ô mà loại ứng dụng đã tự bật"
+    - "Thiếu loại ứng dụng bắt buộc, ví dụ chưa khai ứng dụng api hoặc chưa khai ứng dụng migrate dù đã khai kết nối cơ sở dữ liệu"
+  nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa hfs.json theo lời nhắn của bộ kiểm tra; không cần ai can thiệp thêm."
+  owner: op-retry
+  kind: check-finding
+
+HFS_FORBIDDEN_PRESENT:
+  title: "Tracked path in a forbidden slot"
+  title_vi: "Có tệp bị cấm trong cây mã nguồn"
+  meaning_vi: "Tệp được theo dõi nằm trong một ô bị cấm (bộ nhớ đệm công cụ, đầu ra của tác tử, worktree, tệp bí mật dạng rõ). Ô này quy định nơi tệp phải ở, ngoài kho."
+  causes_vi:
+    - "Tác tử để lại tệp tạm hoặc báo cáo ở gốc kho rồi bị commit"
+    - "Tệp .env hoặc khoá bí mật dạng rõ nằm trong kho"
+    - "Thư mục e2e ở gốc thay vì src/tests/e2e"
+  nextStep_vi: "Chuyển tệp tới nơi ô đó chỉ định (trường goesTo) hoặc xoá nó, rồi gỡ khỏi Git; tệp bí mật phải được niêm phong đúng chỗ, không bao giờ để dạng rõ. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra; không cần ai can thiệp thêm."
+  owner: op-retry
+  kind: check-finding
+
+HFS_INIT_EXISTS:
+  title: "hfs.json already exists"
+  title_vi: "hfs.json đã có sẵn"
+  meaning_vi: "Lệnh hfs init không ghi đè bản khai báo đã có vì bản đó là quyết định của kho."
+  causes_vi:
+    - "Chạy hfs init trong kho đã có hfs.json"
+  nextStep_vi: "Sửa hfs.json trực tiếp, hoặc dùng hfs init --stdout để xem bản dò tự động rồi so sánh."
+  owner: op-retry
+  kind: verb-refusal
+
+HFS_INIT_UNDETECTED:
+  title: "Repository profile or apps not detected"
+  title_vi: "Không dò được loại kho hoặc ứng dụng"
+  meaning_vi: "Lệnh hfs init không xác định chắc chắn kho là backend hay frontend, hoặc không thấy ứng dụng nào dưới apps/ để khai báo, nên không đoán mò."
+  causes_vi:
+    - "Không có next hay @nestjs/core trong phụ thuộc, hoặc có cả hai"
+    - "Kho chưa có thư mục apps/<tên>/ (Nest cần thêm src/, Next cần next.config)"
+  nextStep_vi: "Tạo bố cục apps/<tên>/ theo chuẩn hoặc viết hfs.json bằng tay theo modules/schemas/hfs-repo.schema.yaml."
+  owner: op-retry
+  kind: verb-refusal
+
+HFS_MANIFEST_INVALID:
+  title: "HFS slot manifest invalid"
+  title_vi: "Bảng kê ô HFS sai định dạng"
+  meaning_vi: "Tệp knowledge/hfs/slots.yaml của bộ chạy không đọc được hoặc vi phạm lược đồ của nó, nên mọi kiểm tra HFS bị từ chối chứ không chạy trên một bảng kê hỏng."
+  causes_vi:
+    - "Một ô thiếu trường bắt buộc, dùng giá trị ngoài danh sách cho phép hoặc trùng mã với ô khác"
+    - "Ma trận hướng import nhắc tới một tầng không tồn tại"
+    - "Hai ô cùng khai một mẫu đường dẫn, hoặc một ô đã ngừng dùng mà không chỉ ra ô kế nhiệm"
+  nextStep_vi: "Đây là lỗi của bộ chạy, không phải của sản phẩm; người giám sát sửa knowledge/hfs/slots.yaml qua một nhánh đã được duyệt, sản phẩm không tự sửa."
+  owner: supervisor
+  kind: check-finding
+
+HFS_MANIFEST_MAJOR_MISMATCH:
+  title: "hfs.json pins another manifest major"
+  title_vi: "Phiên bản chính của bảng kê không khớp"
+  meaning_vi: "Trường hfs trong hfs.json ghim một phiên bản chính khác với bảng kê ô của bộ chạy. HFS không có giai đoạn tương thích: khi phiên bản chính mới được nạp thì phiên bản chính cũ bị từ chối ngay."
+  causes_vi:
+    - "Bộ chạy đã lên phiên bản chính mới của bảng kê nhưng kho chưa được di chuyển sang"
+    - "hfs.json ghi số phiên bản chính sai hoặc chép từ một kho khác"
+  nextStep_vi: "Chủ sở hữu duyệt một nhánh di chuyển cho kho này rồi mới đổi số hfs; không có cách bỏ qua hay giữ song song hai phiên bản."
+  owner: owner
+  kind: check-finding
+
+HFS_MIN_INSTANCES:
+  title: "Fewer instances of a slot than required"
+  title_vi: "Số thực thể của ô ít hơn mức tối thiểu"
+  meaning_vi: "Một ô đòi có ít nhất một số thực thể (ví dụ ít nhất một tính năng trong src/features) nhưng kho có ít hơn."
+  causes_vi:
+    - "Kho chưa có tính năng nào đúng mẫu src/features/<tên>/"
+    - "Toàn bộ mã nghiệp vụ nằm ở chỗ ngoài mẫu nên không được tính"
+  nextStep_vi: "Chuyển mã nghiệp vụ vào thực thể đúng mẫu của ô hoặc tạo thực thể còn thiếu. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra; không cần ai can thiệp thêm."
+  owner: op-retry
+  kind: check-finding
+
+HFS_PATH_NO_SLOT:
+  title: "Path matches no HFS slot"
+  title_vi: "Đường dẫn không khớp ô nào của HFS"
+  meaning_vi: "Một tệp hoặc thư mục trong kho không thuộc ô nào trong bảng kê; mọi đường dẫn được theo dõi phải khớp đúng một ô. Bộ kiểm tra báo kèm ô gần nhất để biết tệp lẽ ra thuộc đâu."
+  causes_vi:
+    - "Tệp đặt sai chỗ, ví dụ một tệp không phải *.e2e-spec.ts nằm trong thư mục kiểm thử e2e"
+    - "Thư mục do kho tự đặt ở gốc hoặc trong src mà HFS không có ô cho nó"
+    - "Tên tệp hoặc thư mục viết sai so với mẫu của ô gần nhất"
+  nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để chuyển tệp vào ô gần nhất được báo hoặc xoá nó; nếu thực sự cần một loại nội dung mới thì đó là việc thêm ô vào bảng kê, do người giám sát làm, không phải kho tự thêm."
+  owner: op-retry
+  kind: check-finding
+
+HFS_REPO_UNREADABLE:
+  title: "Repository is not a readable Git work tree"
+  title_vi: "Không đọc được kho Git"
+  meaning_vi: "Bộ kiểm tra HFS chỉ xét những gì Git theo dõi nên cần một cây làm việc Git đọc được; thư mục được chỉ định thì không."
+  causes_vi:
+    - "Đường dẫn --repo sai hoặc không phải kho Git"
+    - "Git chưa cài hoặc kho bị hỏng"
+  nextStep_vi: "Trỏ --repo vào gốc một kho Git hợp lệ rồi chạy lại."
+  owner: op-retry
+  kind: input-invalid
+
+HFS_REQUIRED_MISSING:
+  title: "Required file or directory missing"
+  title_vi: "Thiếu tệp hoặc thư mục bắt buộc"
+  meaning_vi: "Một ô bắt buộc (hoặc một thực thể của ô, như một ứng dụng hay một tính năng) đòi có tệp hoặc thư mục này nhưng nó không nằm trong những gì Git theo dõi."
+  causes_vi:
+    - "Tính năng thiếu index.ts, tệp module hoặc thư mục application"
+    - "Ứng dụng thiếu main.ts, app.module.ts hoặc spec ghép ứng dụng"
+    - "Kho thiếu tệp gốc bắt buộc như README.md, hfs.json, .starciwork, .starcistacks"
+  nextStep_vi: "Tạo tệp hoặc thư mục theo mẫu của ô rồi commit; tệp chưa git add vẫn tính là thiếu. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra; không cần ai can thiệp thêm."
+  owner: op-retry
+  kind: check-finding
+
+HFS_SIZE_SOFT_BACKLOG:
+  title: "Source file above the soft size"
+  title_vi: "Tệp mã vượt cỡ mềm (chỉ báo cáo)"
+  meaning_vi: "Tệp mã nguồn dài hơn ngưỡng mềm của ruleParams.fileLines.soft. Đây là danh mục việc cần tách dần, chỉ báo cáo và không bao giờ làm bộ kiểm tra thất bại."
+  causes_vi:
+    - "Tệp tích tụ qua nhiều lần sửa mà chưa được tách"
+  nextStep_vi: "Không cần hành động ngay; khi sửa tệp này, tách theo trách nhiệm để không tăng thêm. Quy tắc tăng trưởng HFS_SIZE_GROWTH mới là chỗ chặn tệp vượt ngưỡng lớn thêm."
+  owner: op-retry
+  kind: check-finding
+
+HFS_SLOT_AMBIGUOUS:
+  title: "Path owned equally by two slots"
+  title_vi: "Đường dẫn thuộc hai ô cùng mức cụ thể"
+  meaning_vi: "Hai ô của bảng kê cùng khớp một đường dẫn với độ cụ thể bằng nhau nên không xác định được ô nào sở hữu. Đây là chỗ hở của bảng kê, không phải lỗi của kho."
+  causes_vi:
+    - "Hai mẫu đường dẫn trong bảng kê chồng lên nhau"
+    - "Một ô mới thêm chưa loại phần trùng với ô cũ"
+  nextStep_vi: "Người giám sát sửa bảng kê để mỗi đường dẫn chỉ có một ô sở hữu; kho không tự xử lý. Bộ kiểm tra chạy lại sau khi bảng kê được sửa."
+  owner: op-retry
+  kind: check-finding
+
+HFS_SLOT_NOT_ENABLED:
+  title: "Path in an opt-in slot the repository did not enable"
+  title_vi: "Đường dẫn thuộc ô tuỳ chọn mà kho chưa bật"
+  meaning_vi: "Tệp được theo dõi nằm trong một ô loại tuỳ chọn, nhưng hfs.json không liệt kê ô đó trong optionalSlots và không có ứng dụng nào thuộc loại tự bật ô đó."
+  causes_vi:
+    - "Kho dùng một loại nội dung tuỳ chọn (worker, websocket, tài liệu, gói dùng chung) mà chưa khai báo"
+    - "Ứng dụng của loại tương ứng chưa được ghi vào apps của hfs.json"
+  nextStep_vi: "Khai báo ô trong optionalSlots hoặc khai ứng dụng đúng loại ở hfs.json nếu nội dung này là thật; nếu không thì chuyển hoặc xoá tệp. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra; không cần ai can thiệp thêm."
+  owner: op-retry
+  kind: check-finding
+
+HFS_TRACKED_MUST_BE_IGNORED:
+  title: "Tracked path that must be gitignored"
+  title_vi: "Tệp bị theo dõi nhưng lẽ ra phải bị bỏ qua"
+  meaning_vi: "Tệp nằm trong một ô loại ignored (kết quả build, tệp sinh tự động, phụ thuộc) nhưng đã được đưa vào Git."
+  causes_vi:
+    - "Thư mục dist, coverage, .next hoặc tệp sinh tự động bị git add"
+    - ".gitignore thiếu dòng cho thư mục này"
+  nextStep_vi: "Gỡ tệp khỏi Git bằng git rm --cached và thêm vào khối .gitignore chuẩn; không xoá thư mục trên đĩa. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra; không cần ai can thiệp thêm."
+  owner: op-retry
+  kind: check-finding

package/runtime/scripts/lib/glob.mjs

@@ -0,0 +1,23 @@
+// glob.mjs — the path-glob subset ESLint, SonarQube and the scoped-lint config share: `**` spans directories,
+// `*` and `?` stay inside one segment, `{a,b}` alternates.
+import { posixPath } from './path-key.mjs';
+
+/** Every alternative a `{a,b}` pattern spells, braces expanded left to right. */
+export function braceVariants(value) {
+  const match = /\{([^{}]+)\}/.exec(value);
+  return match ? match[1].split(',').flatMap((part) => braceVariants(`${value.slice(0, match.index)}${part}${value.slice(match.index + match[0].length)}`)) : [value];
+}
+
+/** The anchored RegExp of one brace-free glob, read as a posix path (backslashes and a leading './' folded). */
+export function globExpression(value) {
+  const input = posixPath(value);
+  let source = '';
+  for (let i = 0; i < input.length; i += 1) {
+    const c = input[i];
+    if (c === '*' && input[i + 1] === '*') { i += 1; if (input[i + 1] === '/') { i += 1; source += '(?:.*/)?'; } else source += '.*'; }
+    else if (c === '*') source += '[^/]*';
+    else if (c === '?') source += '[^/]';
+    else source += /[.+^${}()|[\]\\]/.test(c) ? `\\${c}` : c;
+  }
+  return new RegExp(`^${source}$`);
+}

package/runtime/scripts/lib/hfs-check.mjs

@@ -0,0 +1,305 @@
+// hfs-check.mjs - the HFS repository check, behind `hfs check | init | explain` (packages/hfs) and reusable by any
+// runtime check. It reads three things and nothing else: the repository's hfs.json, the slot manifest
+// (knowledge/hfs/slots.yaml through scripts/lib/hfs-slots.mjs) and the pins (knowledge/hfs/canon-pins.yaml). It never
+// writes to the repository it inspects.
+//
+// checkRepo() answers, for the tracked paths of one repository (git ls-files):
+//   HFS_PATH_NO_SLOT              a tracked path no slot owns (the nearest slot is named)
+//   HFS_SLOT_NOT_ENABLED          a tracked path in an opt-in slot the repository did not declare
+//   HFS_SLOT_AMBIGUOUS            two slots of equal specificity own the path (a manifest gap, reported not guessed)
+//   HFS_TRACKED_MUST_BE_IGNORED   a tracked path in an `ignored` slot (build output, generated files)
+//   HFS_FORBIDDEN_PRESENT         a tracked path in a forbidden / `external` slot
+//   HFS_REQUIRED_MISSING          a file or directory a required slot (or an instance of one) must contain
+//   HFS_MIN_INSTANCES             fewer instances of a slot than minInstances
+//   HFS_CANON_PIN_DRIFT           a dependency whose declared version is not the pinned one
+//   HFS_SIZE_SOFT_BACKLOG         (info, report-only, never fails) a source file above ruleParams fileLines.soft
+// Every finding carries its code and the Vietnamese why text of modules/kernel/failure-codes.yaml. Only `error`
+// findings fail the check.
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { skillRoot } from '../../engine/runtime-root.mjs';
+import { parseYaml } from '../../engine/yaml.mjs';
+import { HFS_DECLARATION_FILE, HfsSlotsError, createSlotResolver, loadSlotManifest, readRepoDeclaration, resolveRepoDeclaration } from './hfs-slots.mjs';
+import { posixPath } from './path-key.mjs';
+
+export const CANON_PINS_FILE = 'knowledge/hfs/canon-pins.yaml';
+export const FAILURE_CODES_FILE = 'modules/kernel/failure-codes.yaml';
+/** The codes this module emits that are not the slot loader's own: the why bundle of packages/hfs ships exactly these plus the loader's. */
+export const CHECK_CODES = Object.freeze([
+  'HFS_PATH_NO_SLOT', 'HFS_SLOT_NOT_ENABLED', 'HFS_SLOT_AMBIGUOUS', 'HFS_TRACKED_MUST_BE_IGNORED', 'HFS_FORBIDDEN_PRESENT',
+  'HFS_REQUIRED_MISSING', 'HFS_MIN_INSTANCES', 'HFS_CANON_PIN_DRIFT', 'HFS_SIZE_SOFT_BACKLOG',
+  'HFS_INIT_EXISTS', 'HFS_INIT_UNDETECTED', 'HFS_REPO_UNREADABLE',
+  'HFS_DECLARATION_INVALID', 'HFS_MANIFEST_MAJOR_MISMATCH', 'HFS_MANIFEST_INVALID',
+]);
+const SOURCE_EXT = /\.(?:[cm]?[jt]sx?)$/;
+const VAR = /<([a-z][a-z0-9-]*)>/g;
+const DEP_SECTIONS = ['dependencies', 'devDependencies'];
+
+const refuse = (code, message, details = {}) => { throw new HfsSlotsError(code, message, details); };
+
+/** {code: {title_vi, meaning_vi, nextStep_vi}} for the codes asked for, read from the failure-code catalog under `root`. */
+export function readWhy(root = skillRoot, codes = CHECK_CODES) {
+  const catalog = parseYaml(fs.readFileSync(path.join(root, FAILURE_CODES_FILE), 'utf8'));
+  const why = {};
+  for (const code of codes) {
+    const entry = catalog?.[code];
+    if (!entry) refuse('HFS_MANIFEST_INVALID', `${FAILURE_CODES_FILE} has no entry for ${code}`, { code });
+    why[code] = { titleVi: entry.title_vi, whyVi: entry.meaning_vi, nextStepVi: entry.nextStep_vi };
+  }
+  return why;
+}
+
+/** Repository-relative tracked paths (git ls-files, posix separators; what the index holds, whatever the work tree shows). A directory that is not a Git work tree is a refusal. */
+export function trackedFiles(repoRoot) {
+  let out;
+  try {
+    out = execFileSync('git', ['-C', repoRoot, 'ls-files', '-z', '--cached', '--exclude-standard'], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (error) {
+    refuse('HFS_REPO_UNREADABLE', `${repoRoot} is not a readable Git work tree (${String(error?.stderr ?? error?.message ?? error).trim().split('\n')[0]})`, { repoRoot });
+  }
+  return out.split('\0').filter(Boolean).map(posixPath);
+}
+
+const fill = (text, bindings) => String(text).replace(VAR, (whole, name) => bindings[name] ?? whole);
+
+/** hfs.json of `repoRoot` resolved against the manifest, or the single refusal finding when it is absent or invalid. */
+export function openRepo({ repoRoot, root = skillRoot, manifest = loadSlotManifest({ root }) }) {
+  const repo = readRepoDeclaration(manifest, repoRoot);
+  return { manifest, repo, resolver: createSlotResolver(manifest, repo) };
+}
+
+const pinnedSpec = (spec, pin) => (spec === pin.version ? null : `declared ${spec}, pinned ${pin.version}`);
+
+function pinFindings({ repoRoot, files, profile, root }) {
+  const pins = parseYaml(fs.readFileSync(path.join(root, CANON_PINS_FILE), 'utf8'))?.pins ?? {};
+  const findings = [];
+  for (const file of files.filter((f) => f === 'package.json' || f.endsWith('/package.json'))) {
+    let pkg;
+    try { pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, file), 'utf8')); } catch { continue; }
+    for (const [name, pin] of Object.entries(pins)) {
+      if (pin.side !== 'both' && pin.side !== profile) continue;
+      for (const section of DEP_SECTIONS) {
+        const spec = pkg[section]?.[name];
+        if (spec === undefined) continue;
+        const drift = pinnedSpec(spec, pin);
+        if (drift) findings.push({ code: 'HFS_CANON_PIN_DRIFT', level: 'error', path: file, dependency: name, section, pinned: pin.version, declared: spec, message: `${name} in ${file} ${section}: ${drift}` });
+      }
+    }
+  }
+  return findings;
+}
+
+/** Instances (slot, root, bindings) present in the tracked tree, for every slot that names required files or a minimum. */
+function instancesOf(resolver, files) {
+  const found = new Map();
+  const note = (slotId, root, bindings) => {
+    const slot = resolver.slot(slotId);
+    if (!slot || !(slot.requires?.length || slot.minInstances)) return;
+    const key = `${slotId}|${root}`;
+    if (!found.has(key)) found.set(key, { slot: slotId, root, bindings });
+  };
+  for (const file of files) {
+    const c = resolver.classifyPath(file);
+    if (c.status === 'owned') note(c.slot, c.root, c.bindings);
+    const owner = c.status === 'owned' ? resolver.ownerOf(file) : null;
+    if (owner) note(owner.slot, owner.root, owner.bindings);
+  }
+  return [...found.values()];
+}
+
+const requiredOf = (slot, instance) => (slot.requires ?? []).map((entry) => {
+  const rooted = entry.startsWith('/');
+  const filled = fill(rooted ? entry.slice(1) : entry, instance.bindings);
+  return rooted || !instance.root ? filled : `${instance.root}/${filled}`;
+});
+
+const appOf = (p) => /^apps\/([^/]+)\//.exec(p)?.[1];
+
+function withWhy(findings, why) {
+  return findings.map((f) => ({ ...f, titleVi: why[f.code].titleVi, whyVi: why[f.code].whyVi, nextStepVi: why[f.code].nextStepVi }));
+}
+
+function summarize(findings) {
+  const byCode = {};
+  for (const f of findings) {
+    byCode[f.code] ??= { level: f.level, count: 0 };
+    byCode[f.code].count += 1;
+  }
+  return {
+    error: findings.filter((f) => f.level === 'error').length,
+    info: findings.filter((f) => f.level === 'info').length,
+    byCode,
+  };
+}
+
+/**
+ * The check of one repository. `declaration` overrides hfs.json (a dry run over a repository that has none); `files`
+ * overrides git ls-files (specs). Returns {ok, profile, apps, manifest, tracked, findings, counts}; a missing or invalid
+ * hfs.json is one HFS_DECLARATION_INVALID / HFS_MANIFEST_MAJOR_MISMATCH error finding, never an exception.
+ */
+export function checkRepo({ repoRoot, root = skillRoot, declaration, files, manifest = loadSlotManifest({ root }) }) {
+  const why = readWhy(root);
+  let repo;
+  try {
+    repo = declaration === undefined ? readRepoDeclaration(manifest, repoRoot) : resolveRepoDeclaration(manifest, declaration);
+  } catch (error) {
+    if (!(error instanceof HfsSlotsError) || !['HFS_DECLARATION_INVALID', 'HFS_MANIFEST_MAJOR_MISMATCH'].includes(error.code)) throw error;
+    const findings = withWhy([{ code: error.code, level: 'error', path: HFS_DECLARATION_FILE, message: error.message.replace(/^[A-Z_]+: /, ''), problems: error.details.problems }], why);
+    return { ok: false, repoRoot, manifest: manifest.version, profile: null, apps: [], tracked: 0, findings, counts: summarize(findings) };
+  }
+  const resolver = createSlotResolver(manifest, repo);
+  const tracked = files ?? trackedFiles(repoRoot);
+  const trackedSet = new Set(tracked);
+  const present = (p) => (p.endsWith('/') ? tracked.some((f) => f.startsWith(p)) : trackedSet.has(p));
+  const findings = [];
+
+  for (const file of tracked) {
+    const c = resolver.classifyPath(file);
+    if (c.status === 'no-slot') {
+      findings.push({ code: 'HFS_PATH_NO_SLOT', level: 'error', path: file, nearest: c.nearest, message: `${file} matches no slot${c.nearest ? `; nearest slot ${c.nearest.slot} (${c.nearest.pattern}), matched ${c.nearest.matchedPrefix || '.'} then expected ${c.nearest.expectedNext ?? 'nothing'}` : ''}` });
+    } else if (c.status === 'ambiguous') {
+      findings.push({ code: 'HFS_SLOT_AMBIGUOUS', level: 'error', path: file, candidates: c.candidates, message: `${file} is owned equally by ${c.candidates.map((x) => x.slot ?? x).join(', ')}` });
+    } else if (c.status === 'not-enabled') {
+      findings.push({ code: 'HFS_SLOT_NOT_ENABLED', level: 'error', path: file, slot: c.slot, message: `${file} belongs to ${c.slot}, an opt-in slot hfs.json neither lists in optionalSlots nor implies through an app kind` });
+    } else if (c.status === 'forbidden') {
+      findings.push({ code: 'HFS_FORBIDDEN_PRESENT', level: 'error', path: file, slot: c.slot, goesTo: c.goesTo, message: `${file} is tracked but ${c.slot} is forbidden in the tree${c.goesTo ? `; it belongs at ${c.goesTo}` : ''}` });
+    } else if (c.tracking === 'ignored') {
+      findings.push({ code: 'HFS_TRACKED_MUST_BE_IGNORED', level: 'error', path: file, slot: c.slot, message: `${file} is tracked but ${c.slot} must be gitignored` });
+    }
+  }
+
+  const required = resolver.requiredPaths();
+  const missing = new Set();
+  const missingFile = (slot, p, via) => {
+    const key = `${slot}|${p}`;
+    if (missing.has(key) || present(p)) return;
+    missing.add(key);
+    const app = appOf(p);
+    findings.push({ code: 'HFS_REQUIRED_MISSING', level: 'error', path: p, slot, via, ...(app ? { app } : {}), message: `${slot} requires ${p}${app ? ` (app ${app})` : ''}, which is not tracked` });
+  };
+  for (const entry of required.paths) missingFile(entry.slot, entry.path, entry.via);
+  const instances = instancesOf(resolver, tracked);
+  for (const instance of instances) for (const p of requiredOf(resolver.slot(instance.slot), instance)) missingFile(instance.slot, p, 'requires');
+  for (const { slot, min, appKind } of required.minimums) {
+    if (appKind !== undefined) continue;     // an app-kind minimum is checked by requiredPaths (one path set per declared app)
+    const count = instances.filter((i) => i.slot === slot).length;
+    if (count < min) findings.push({ code: 'HFS_MIN_INSTANCES', level: 'error', path: resolver.slot(slot).path, slot, min, count, message: `${slot} needs at least ${min} instance${min === 1 ? '' : 's'} (${resolver.slot(slot).path}), found ${count}` });
+  }
+
+  findings.push(...pinFindings({ repoRoot, files: tracked, profile: repo.profile, root }));
+
+  const soft = resolver.ruleParams().fileLines.soft;
+  for (const file of tracked) {
+    if (!SOURCE_EXT.test(file) || resolver.classifyPath(file).status !== 'owned') continue;
+    let lines;
+    try { lines = fs.readFileSync(path.join(repoRoot, file), 'utf8').split('\n').length; } catch { continue; }
+    if (lines > soft) findings.push({ code: 'HFS_SIZE_SOFT_BACKLOG', level: 'info', path: file, lines, soft, message: `${file} has ${lines} lines, above the soft size ${soft}; report only` });
+  }
+
+  const finished = withWhy(findings, why);
+  const counts = summarize(finished);
+  return { ok: counts.error === 0, repoRoot, manifest: manifest.version, profile: repo.profile, apps: repo.apps, tracked: tracked.length, findings: finished, counts };
+}
+
+// --------------------------------------------------------------------------------------------------- explain
+
+const TEST_KIND = {
+  'unit-beside': 'a unit spec beside each source file (<name>.spec.ts / .spec.tsx) in this slot',
+  e2e: 'an e2e spec (*.e2e-spec.ts or a Playwright spec) covering the flow; no unit spec is required',
+  none: 'no test is required for files in this slot',
+};
+
+/** What owns `input` and what that means: slot, tier, allowed imports, required tests, required files. */
+export function explainPath({ repoRoot, input, root = skillRoot, declaration, manifest = loadSlotManifest({ root }) }) {
+  const repo = declaration === undefined ? readRepoDeclaration(manifest, repoRoot) : resolveRepoDeclaration(manifest, declaration);
+  const resolver = createSlotResolver(manifest, repo);
+  const why = readWhy(root);
+  const c = resolver.classifyPath(input);
+  if (c.status === 'no-slot') {
+    return { path: c.path, status: 'no-slot', code: 'HFS_PATH_NO_SLOT', nearest: c.nearest, titleVi: why.HFS_PATH_NO_SLOT.titleVi, whyVi: why.HFS_PATH_NO_SLOT.whyVi };
+  }
+  if (c.status === 'ambiguous') return { path: c.path, status: 'ambiguous', code: 'HFS_SLOT_AMBIGUOUS', candidates: c.candidates, titleVi: why.HFS_SLOT_AMBIGUOUS.titleVi, whyVi: why.HFS_SLOT_AMBIGUOUS.whyVi };
+  const slot = resolver.slot(c.slot);
+  const tier = resolver.tierOf(c.path);
+  const owner = resolver.ownerOf(c.path);
+  const mayImport = tier && tier !== 'none' ? resolver.allowedImports(tier) : null;
+  return {
+    path: c.path,
+    status: c.status,
+    slot: slot.id,
+    pattern: slot.path,
+    presence: slot.presence,
+    tracking: slot.tracked,
+    tier: tier ?? 'none',
+    owner: owner ? { slot: owner.slot, root: owner.root } : null,
+    allowedImports: mayImport,
+    importRule: mayImport ? manifest.crossOwner : (tier === 'none' ? 'the slot takes no part in import checks' : null),
+    tests: slot.tests,
+    testsMeaning: TEST_KIND[slot.tests],
+    requiredFiles: resolver.requiredFiles(c.path),
+    ...(slot.goesTo ? { goesTo: slot.goesTo } : {}),
+    ...(slot.rules ? { rules: slot.rules } : {}),
+    ...(c.status === 'forbidden' ? { code: 'HFS_FORBIDDEN_PRESENT', titleVi: why.HFS_FORBIDDEN_PRESENT.titleVi, whyVi: why.HFS_FORBIDDEN_PRESENT.whyVi } : {}),
+    ...(c.status === 'not-enabled' ? { code: 'HFS_SLOT_NOT_ENABLED', titleVi: why.HFS_SLOT_NOT_ENABLED.titleVi, whyVi: why.HFS_SLOT_NOT_ENABLED.whyVi } : {}),
+  };
+}
+
+// ------------------------------------------------------------------------------------------------- init
+
+const SLUG_SUFFIX = /-(backend|be|frontend|fe|api|web|app)$/;
+const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+const exists = (p) => fs.existsSync(p);
+const readPackage = (dir) => { try { return JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')); } catch { return null; } };
+const depsOf = (pkg) => ({ ...pkg?.devDependencies, ...pkg?.dependencies });
+
+/**
+ * A starter hfs.json by detection: profile from the dependencies (next -> fe, @nestjs/core -> be, over the root and
+ * every apps/<name>), apps from the apps/<name> directories (fe: kind next; be: worker/migrate/cli by name, else api).
+ * optionalSlots are the opt-in slots (not implied by an app kind) that tracked files already occupy. Connections are not guessed; a repository that keeps a database declares them by hand and gains the migrate app.
+ * A repository the detection cannot classify is HFS_INIT_UNDETECTED, never a guess.
+ */
+export function detectDeclaration({ repoRoot, manifest }) {
+  const appsDir = path.join(repoRoot, 'apps');
+  const names = isDir(appsDir) ? fs.readdirSync(appsDir, { withFileTypes: true }).filter((e) => e.isDirectory() && e.name !== 'node_modules').map((e) => e.name).sort() : [];
+  const rootPkg = readPackage(repoRoot);
+  const all = { ...depsOf(rootPkg) };
+  for (const name of names) Object.assign(all, depsOf(readPackage(path.join(appsDir, name))));
+  const isFe = 'next' in all || names.some((n) => ['next.config.ts', 'next.config.js', 'next.config.mjs'].some((f) => exists(path.join(appsDir, n, f))));
+  const isBe = '@nestjs/core' in all || exists(path.join(repoRoot, 'nest-cli.json'));
+  if (isFe === isBe) refuse('HFS_INIT_UNDETECTED', `cannot tell the profile of ${repoRoot}: ${isFe ? 'both next and Nest are present' : 'neither next nor @nestjs/core is declared'}`, { repoRoot });
+  const profile = isFe ? 'fe' : 'be';
+  const apps = names.map((name) => {
+    if (profile === 'fe') return { name, kind: 'next' };
+    if (!isDir(path.join(appsDir, name, 'src'))) return null;
+    const kind = /migrat/.test(name) ? 'migrate' : (/worker/.test(name) ? 'worker' : (/(^|-)cli($|-)/.test(name) ? 'cli' : 'api'));
+    return { name, kind };
+  }).filter(Boolean).filter((a) => manifest.appKinds[profile].includes(a.kind));
+  if (!apps.length) refuse('HFS_INIT_UNDETECTED', `${repoRoot} has no apps/<name> ${profile === 'fe' ? 'Next application' : 'Nest application with a src directory'} to declare`, { repoRoot, profile });
+  const project = String(rootPkg?.name ?? path.basename(repoRoot)).replace(/^@[^/]+\//, '').toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').replace(SLUG_SUFFIX, '');
+  const declaration = { hfs: manifest.major, profile, project: /^[a-z]/.test(project) ? project : `p-${project}`, apps };
+  const optionalSlots = occupiedOptInSlots({ repoRoot, manifest, declaration });
+  return optionalSlots.length ? { ...declaration, optionalSlots } : declaration;
+}
+
+/** The opt-in slots (not enabled by an app kind) that at least one tracked file falls in, found by enabling them all for a look. */
+function occupiedOptInSlots({ repoRoot, manifest, declaration }) {
+  let files;
+  try { files = trackedFiles(repoRoot); } catch (error) { if (error.code === 'HFS_REPO_UNREADABLE') return []; throw error; }
+  const optIn = manifest.slots.filter((s) => s.profiles.includes(declaration.profile) && s.presence === 'opt-in' && s.appKind === undefined).map((s) => s.id);
+  const everything = createSlotResolver(manifest, resolveRepoDeclaration(manifest, { ...declaration, optionalSlots: optIn }));
+  const used = new Set();
+  for (const file of files) { const c = everything.classifyPath(file); if (c.status === 'owned' && optIn.includes(c.slot)) used.add(c.slot); }
+  return optIn.filter((id) => used.has(id));
+}
+
+/** Write hfs.json unless one exists (HFS_INIT_EXISTS); `write: false` returns the text only. */
+export function initRepo({ repoRoot, root = skillRoot, write = true, manifest = loadSlotManifest({ root }) }) {
+  const file = path.join(repoRoot, HFS_DECLARATION_FILE);
+  if (write && exists(file)) refuse('HFS_INIT_EXISTS', `${file} already exists; init never rewrites a declaration`, { file });
+  const declaration = detectDeclaration({ repoRoot, manifest });
+  resolveRepoDeclaration(manifest, declaration);
+  const text = `${JSON.stringify(declaration, null, 2)}\n`;
+  if (write) fs.writeFileSync(file, text);
+  return { file, declaration, text, written: write };
+}