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

## 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".

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.