# Pk Lint

> Kiểm tra sức khoẻ hệ thống .cockpit/: link hỏng, registry lệch, file mồ côi, schema cũ. 3 mode: check (rà soát read-only), fix (sửa + rebuild index), evolve (nâng cấp schema). Dùng khi user nói 'lint', 'kiểm tra hệ thống', 'dọn dẹp cockpit', 'audit', 'rebuild index', hoặc nghi ngờ dữ liệu cockpit bị lệch.

- Skill: `hoangvantuan/pk-lint` (Agent Skill)
- Install (CLI): `npx skillmds@latest add hoangvantuan/pk-lint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hoangvantuan/pk-lint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: hoangvantuan (https://skillmd.com/u/hoangvantuan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hoangvantuan/pk-lint

---


# PK Lint: Rà soát + sửa chữa hệ thống

## Ensure snapshot (bắt buộc, đầu flow)

1. **Precondition**: `.cockpit/` tồn tại. Thiếu → route `pk-init` (mode new), KHÔNG nạp gì thêm, dừng.
2. **Idempotent qua marker**: phiên CHƯA có marker `SNAPSHOT_LOADED` → tự nạp full theo Snapshot Contract
   (`../pk-shared/references/snapshot-contract.md`) rồi đặt marker `SNAPSHOT_LOADED`. Đã có marker (vd
   harness Phase 1 đã đặt) → skip, không đọc lại.

3 mode: **check** (mặc định, read-only), **fix** (consolidation + rebuild + restore), **evolve** (schema-review).

## Mode check (health check, read-only)

Ranh giới: pk-analyze đếm số liệu tổng cho dashboard. pk-lint soi chi tiết từng file.

### Hạng mục kiểm tra

**1. Registry sync**
- knowledge/index.md: mỗi entry → file tồn tại. File trong knowledge/ không trong index → báo.
- skills/registry.md, workflows/registry.md: tương tự.

**2. Link integrity**
- Quét mọi cross-reference nội bộ cockpit: `[[slug]]`, `[text](path)`, frontmatter `related`, `source_file`, frontmatter `skills_used: [...]` của workflow, marker `→ Skill: [[X]]` trong procedure block
- Resolve: tìm file `{type}-{slug}.md` trong knowledge/, skills/, workflows/. Kiểm tra path đích tồn tại.
- **Link mồ côi** (trỏ tới slug đã gộp/deprecate/archive): báo cụ thể file nguồn + tham chiếu hỏng. Đây là lưới an toàn cho sau khi pk-distill grep-rewrite inbound link.
- **Slug trùng** (2 file khác type cùng slug): báo vi phạm bất biến unique-slug (canonical: `../pk-shared/references/schemas.md`, mục "Bất biến unique-slug").
- **Skill con không tồn tại/archive**: khi `skills_used` hoặc `→ Skill: [[X]]` trỏ tới skill đã archive hoặc không tồn tại, báo cụ thể file nguồn + tham chiếu hỏng.
- Link hỏng khác → báo cụ thể (file nguồn, dòng, link hỏng, lý do)

**3. Frontmatter check** (spec: ../pk-shared/references/schemas.md)
- Mọi page: `type`, `title`, `status`, `updated`
- Knowledge: thêm `confidence`
- Skill: thêm `version`, `trigger`, `input`, `output`
- Workflow: thêm `version`, `trigger`
- Thiếu → báo cụ thể

**4. Inbox backlog**
- Tuổi theo `captured_at`, ngưỡng theo Inbox Aging trong ../pk-shared/references/schemas.md. Trong check report:
  - 7-30 ngày → liệt kê tồn đọng
  - > 30 ngày → cảnh báo
- Bổ sung đối chiếu bảng "Ngưỡng nhắc xử lý" (canonical: ../pk-shared/references/schemas.md, cùng mục "Inbox Aging + Ngưỡng nhắc xử lý"): >= 10 item pending, hoặc có item pending > 14 ngày → gợi ý chạy pk-distill/pk-track inbox-only.
- Phân execution vs knowledge.

**5. Reachability audit**
- File trong `.cockpit/` không neo vào SOT → báo mồ côi. Bảng neo SOT canonical: `../pk-shared/references/snapshot-contract.md` mục "Reachability khi ghi". Không chép bảng; trỏ về.
- **Orphan-action**: action có `key_result` null/rỗng, hoặc `key_result` trỏ tới KR không tồn tại trong objective.md → báo `orphan-action` kèm action ID và lý do cụ thể (thiếu field vs. KR không tồn tại).

**6. Knowledge health metrics**
- Page count, freshness, orphans, usage distribution theo ../pk-shared/references/metrics.md, KHÔNG chép công thức

**7. Kiểm thủ công drift prose** (thủ công, không auto)
- (a) README architecture map: đối chiếu sơ đồ cây `.cockpit/` trong README.md với cấu trúc `.cockpit/` thật. Nếu có file/folder mới chưa xuất hiện trong sơ đồ, báo để cập nhật thủ công.
- (b) flows.md: đối chiếu "4 điểm tích hợp" trong `skills/pk-harness/references/flows.md` với bảng cross-call hợp lệ trong `../pk-shared/references/cross-call-rules.md`. Nếu lệch, báo để cập nhật thủ công.
- Hạng mục này KHÔNG tự fix được bằng grep; yêu cầu người dùng xác nhận và sửa.

**8. AGENTS.md sync** (auto-fix được, xem rebuild-index)
- Kiểm `AGENTS.md` tại root workspace có block marker `<!-- personal-assistant:start -->` / `<!-- personal-assistant:end -->` không. Thiếu (kể cả thiếu file, vd project khởi tạo trước khi có feature này) → báo `agents-md-missing`.
- Có block → đối chiếu nội dung giữa marker với format canonical `../pk-shared/references/schemas.md` (mục "AGENTS.md block format"): 6 dòng `@.cockpit/...` đủ và đúng path không, có **đủ 3 mục hành vi** (`### Tự capture khi mạch việc hoàn tất`, `### Dùng lại tri thức đã đúc kết`, `### Nhắc xử lý inbox`) không, block ≤ 45 dòng giữa marker không, mô tả nhiệm vụ còn khớp không. Lệch (kể cả block cũ chỉ có `### Cuối phiên` — tạo trước feature ambient) → báo `agents-md-drift`.
- Khác hạng mục 7: cái này tự fix được (block giữa marker là sổ sách dẫn xuất) → backfill/regenerate ở rebuild-index.

**9. CLAUDE.md liên kết** (CHỈ CẢNH BÁO, KHÔNG tự sửa)
- Kiểm root workspace: `CLAUDE.md` tồn tại VÀ chứa dòng `@AGENTS.md`?
- Thiếu một trong hai → báo `claude-md-not-linked` kèm hướng dẫn 1 dòng: "Thêm dòng `@AGENTS.md` vào CLAUDE.md để quy tắc ambient được nạp mỗi phiên."
- **KHÔNG tự sửa, KHÔNG tạo CLAUDE.md** (việc nối thuộc user — giữ nguyên quy tắc "KHÔNG tạo/sửa CLAUDE.md" ở rebuild-index). Đây là mắt xích quyết định sự sống của toàn bộ ambient flow; thiếu nó thì 3 mục hành vi trong AGENTS.md không bao giờ được nạp.

### Output

```markdown
## Check Report - YYYY-MM-DD

### Registry lệch (N)
### Link hỏng (N)
### Thiếu frontmatter (N)
### Inbox tồn đọng (N)
### Reachability (N) (gồm orphan-action: N)
### Knowledge metrics
### AGENTS.md sync (agents-md-missing / agents-md-drift)
### CLAUDE.md liên kết (claude-md-not-linked)

✅ Không có vấn đề (nếu clean)
```

## Mode fix

### Sub-mode: consolidation (deep audit)

Đọc NỘI DUNG tất cả pages. Rà soát:
- Mâu thuẫn nội dung giữa pages
- Pages chồng chéo → đề xuất gộp
- Pages lỗi thời (> 90 ngày không update) → hạ confidence hoặc archive
- Nhất quán thuật ngữ
- Workflow dependency outdated

Trình report → user duyệt → thực thi thay đổi. Khi ghi đè nội dung page: trước khi ghi, đọc body hiện tại (bất biến: `../pk-shared/references/snapshot-contract.md`, mục "Bất biến đọc body trước khi ghi body").

### Sub-mode: rebuild-index

Sinh lại file dẫn xuất từ nguồn gốc (frontmatter + log), format theo spec ../pk-shared/references/schemas.md:
1. Quét knowledge/*.md → sinh knowledge/index.md (bao gồm cột Redirect từ frontmatter `redirect_to`)
2. Quét skills/*.md → sinh skills/registry.md
3. Quét workflows/*.md → sinh workflows/registry.md
4. **Tái sinh bảng consumer** trong `../pk-shared/SKILL.md`: grep ngược qua tất cả `skills/pk-*/SKILL.md`, tìm dòng tham chiếu `../pk-shared/references/<file>.md`. Với mỗi reference file, liệt kê danh sách skill đang tham chiếu → cập nhật cột "Skill tiêu thụ chính" trong bảng References của `pk-shared/SKILL.md`. Bảng consumer là bản phái sinh; rebuild-index là cơ chế tái sinh chuẩn.
5. **Regenerate AGENTS.md block** (backfill `agents-md-missing` / sửa `agents-md-drift`): ghi lại block giữa marker `<!-- personal-assistant:start/end -->` theo format canonical `../pk-shared/references/schemas.md` (mục "AGENTS.md block format"). Idempotent theo quy tắc ghi tại canonical (tạo mới / append / replace giữa marker). Chỉ động vùng trong marker, KHÔNG đụng nội dung khác của AGENTS.md, KHÔNG tạo/sửa CLAUDE.md.

Cột Usage tái dẫn xuất từ log theo công thức ../pk-shared/references/metrics.md mục "Usage count (canonical)". Fallback: log thiếu thì giữ giá trị Usage cũ trong index; không có giá trị cũ thì để 0. (Usage được tính từ log, không phải frontmatter.) Cột Usage là cache-hint; log là SOT (xem ../pk-shared/references/sot-ownership.md).

Cột Redirect: lấy từ frontmatter `redirect_to`. Rỗng nếu không có hoặc status không phải stub.

### Sub-mode: restore

Khôi phục page/bó từ `archive/`:
1. Xác định mục tiêu (slug hoặc liệt kê archive)
2. Move file về đích. KHÔNG ghi đè nếu xung đột.
3. Đổi `status` → `active`
4. Rebuild index
5. Log

### Fix tự động vs cần duyệt

**Tự fix (sổ sách dẫn xuất)**: registry thiếu/thừa entry so với file thật.
**Cần duyệt**: link hỏng, frontmatter thiếu, inbox tồn, gộp pages.

## Mode evolve (schema-review)

Tổng hợp tín hiệu "khuôn không vừa" → đề xuất diff lên SCHEMA.md.

### Flow

1. Đọc `schema-signals.md` (BỎ QUA promote-candidate)
2. Quét sống: đếm page/type, cụm tag, file phình (KHÔNG dùng cho glossary, xem ghi chú bên dưới)
3. Áp ngưỡng (bảo thủ: thà bỏ sót hơn báo nhiễu). Ngưỡng canonical: `../pk-shared/references/schemas.md`, mục "Bảng ngưỡng emit/act".
4. Sinh đề xuất diff
5. User duyệt
6. Migrate: bump version, rewrite link, rebuild index
7. Move tín hiệu đã batch sang "Đã xử lý" trong schema-signals.md kèm kết quả (duyệt hoặc bác). Chạy cả khi user bác đề xuất.

### 4 loại thay đổi

Ngưỡng đầy đủ (emit-threshold + act-threshold) tại `../pk-shared/references/schemas.md`, mục "Bảng ngưỡng emit/act".

| Thay đổi | Tín hiệu đọc |
| --- | --- |
| Thêm page type | `no-fit-type` |
| Đổi layout (tách subfolder) | (đếm trực tiếp page active) |
| Đổi format (template hoá section) | `adhoc-section` |
| Thêm glossary | `term-repeat` |

Ghi chú:
- query-miss là bằng chứng phụ, không tự kích hoạt thay đổi.
- Dưới ngưỡng: GIỮ tín hiệu, không xoá.
- **Glossary**: đọc tín hiệu `term-repeat` từ schema-signals.md thay cho "quét sống". pk-distill emit `term-repeat` khi xử lý nội dung (đáng tin hơn quét tĩnh).

## Log

```
---
timestamp: YYYY-MM-DDTHH:mm
type: knowledge-activity
source_skill: pk-lint
---
Lint [mode]: N vấn đề, M fixed
```

## Quy tắc

- Check mode thuần read-only.
- Fix: tách phát hiện khỏi quyết định. User duyệt nội dung, tự fix sổ sách.
- Evolve: không auto-migrate. Mọi batch gate qua user.
- Reversibility: không hard delete. Archive.