ĐIỀU 22: LUẬT TỰ SỬA CHỮA + TỰ CẢI TIẾN — v1.2 BAN HÀNH

v1.2 BAN HÀNH | 2026-04-22 | Sửa chui S178 Fix 29 +§1.1 Issue Lifecycle auto-close Base: v1.1 / S178 Fix 15 + Fix 24. Phạm vi amend Fix 29: +§1.1 Vòng đời Issue: 5 cases (insert/idempotent/reopen/auto-close/noop), matching key composite (NT1+Đ14), success gate (NT9), reopen thay tạo mới. Schema: +resolved_at +resolved_by +reopen_count. Config: hc_auto_close_enabled.

§1. Vòng lặp Tự sửa chữa

NHẬN DIỆN → LIỆT KÊ → XỬ LÝ → XÁC NHẬN → CẢI TIẾN → (lặp lại)

NHẬN DIỆN: DOT quét + trigger/flow realtime phát hiện vấn đề.
LIỆT KÊ: ghi system_issues với category, severity, provenance.
XỬ LÝ: tự sửa khi rule rõ; nếu không rõ → tạo APR / task chuẩn hoá.
XÁC NHẬN: quét lại. Pass → đóng issue tự động (§1.1). Fail → escalate.
CẢI TIẾN: pattern lặp lại → đề xuất đổi kiến trúc/quy trình.

§1.1 Vòng đời Issue — Auto-close PG Native (★ S178 Fix 29)

Bước ④ (XÁC NHẬN → đóng) PHẢI tự động, không cần người nhớ, không thể nhầm. Giống khai sinh tự động (Đ4 §2.1): em bé sinh ra → giấy khai sinh tự in. Ở đây: vấn đề hết → hồ sơ tự đóng.

Status lifecycle — PG constraint enforced trên system_issues.status:

Status	Nghĩa	Ai ghi	Khi nào
`open`	Vấn đề đang mở	Executor / fn_log_issue	Phát hiện finding mới (bước ②)
`resolved`	Vấn đề không còn tái xuất	Executor (auto-close)	Run tiếp theo finding không tái xuất + check PASS (bước ④)

Schema bổ sung system_issues:

ALTER constraint chk_system_issues_status thêm giá trị 'resolved'.
ADD COLUMN resolved_at TIMESTAMPTZ — thời điểm đóng.
ADD COLUMN last_seen_at TIMESTAMPTZ — lần cuối finding còn sống (update mỗi run — case B metadata only).
ADD COLUMN resolved_by TEXT — check_code nào đóng.
ADD COLUMN reopen_count INT NOT NULL DEFAULT 0 — đếm tái phát (diagnostic cho bước ⑤ CẢI TIẾN).

Matching key — xác định finding nào tương ứng issue nào (NT14 + NT9 + NT1):

Mỗi bệnh nhân (entity) + mỗi loại bệnh (check) = 1 sổ (issue) duy nhất (NT1 SSOT, Đ14 chống trùng lặp). Composite key match:

Entity-level issue (entity_code NOT NULL): match bằng (source, entity_type, entity_code).
System-level issue (entity_code IS NULL): match bằng (source, issue_type).

5 trường hợp — logic đầy đủ cho executor (NT14 thực thi được ngay):

Case	Issue hiện có	Finding hiện tại	Action
A — Bệnh mới	Không có (open lẫn resolved)	Có	INSERT mới (status=open)
B — Vẫn bệnh cũ, sổ đang mở	Open cùng key	Có	UPDATE last_seen_at=NOW() (metadata only, NT1 + Đ14)
C — Bệnh lại, sổ đã đóng	Resolved cùng key	Có	REOPEN: UPDATE status='open', resolved_at=NULL, resolved_by=NULL, reopen_count=reopen_count+1
D — Hết bệnh, sổ quên đóng	Open cùng key	Không + check OK	AUTO-CLOSE: UPDATE status='resolved', resolved_at=NOW(), resolved_by=check_code
E — Đã khỏi, vẫn khỏe	Resolved cùng key	Không	KHÔNG LÀM GÌ

Cơ chế auto-close — pseudocode cho executor (NT14):

Mỗi executor cycle:

  Cho mỗi check (is_active=true, ORDER BY order_index):
    TRY:
      findings = chạy detect query → danh sách findings (mỗi finding = 1 bộ matching key)
      check_ok = true
    CATCH lỗi SQL/timeout:
      check_ok = false
      fn_log_issue(severity=critical, source=check.code, issue_type='check_error', ...)
      → CONTINUE check tiếp. KHÔNG auto-close, KHÔNG ghi findings.

    ★ Ghi findings (bước ② LIỆT KÊ):
    Cho mỗi finding:
      Tìm issue cùng matching key (bất kỳ status):
        KHÔNG CÓ (case A)   → fn_log_issue INSERT mới (open)
        CÓ, status=open (case B)  → UPDATE last_seen_at=NOW()
        CÓ, status=resolved (case C) → UPDATE status='open', resolved_at=NULL,
                                         resolved_by=NULL, reopen_count+1

    Heal nếu detect_and_fix (bước ③).

    ★ Auto-close (bước ④) — CHỈ KHI check_ok = true:
      current_keys = tập matching keys từ findings
      open_issues = SELECT FROM system_issues
                    WHERE source = check.code AND status = 'open'

      Cho mỗi open_issue:
        NẾU matching key KHÔNG CÒN trong current_keys (case D):
          → UPDATE status='resolved', resolved_at=NOW(), resolved_by=check.code

3 guards bắt buộc:

Success gate: Check phải chạy thành công (check_ok = true). Lỗi SQL/timeout → 0 findings KHÔNG PHẢI "sạch" mà là "mù" → KHÔNG auto-close, KHÔNG ghi findings, ghi CRITICAL.
Scope guard: Auto-close CHỈ áp dụng issues có source khớp system_health_checks.code. Issues từ nguồn khác (manual, other DOT) → KHÔNG đụng.
Config gate: dot_config key hc_auto_close_enabled, default 'true'. False → skip auto-close.

Diagnostic: Entity có reopen_count >= 3 = bệnh mãn tính → signal cho bước ⑤ CẢI TIẾN: cần sửa gốc (kiến trúc/quy trình), không chỉ chữa triệu chứng.

Viện dẫn: NT1 (SSOT — 1 entity + 1 check = 1 issue), NT2 (tự động), NT5 (tự phát hiện sửa), NT9 (success gate), NT13 (PG driven config), NT14 (pseudocode + 5 cases), Đ14 (chống trùng lặp).

§2. Nguyên tắc Sổ kế toán kép

Mọi số liệu quan trọng phải có ít nhất 2 hướng đếm độc lập:

Xuôi (snapshot)
Ngược (transaction log)

Xuôi = Ngược → tin được. Xuôi ≠ Ngược → cảnh báo ngay.

§3. Ba danh mục song song trên Registries

Danh mục	Nội dung	Trạng thái
Danh mục hệ thống	atoms / tổng hợp / cấu trúc	Có
Danh mục vấn đề	lỗi, drift, vi phạm, thiếu dữ liệu	Có
Danh mục cải tiến	đề xuất tối ưu / tiến hoá	Kế hoạch

§4. Chiến lược “Phơi bày ra ánh sáng” — DOT Tầng 5

Mọi vấn đề phải được phơi bày; không giấu, không chờ ai hỏi.

DOT scripts Tầng 5 = hệ thống kiểm tra tự động. Tự chạy → tự phát hiện → tự liệt kê vào system_issues.

§4.1 CẤM Silent-Fail Pattern trong `ops-code/`

Cấm 3 pattern sau khi chúng ảnh hưởng control-flow, gate, validation, mutation hoặc che khuất lỗi thực thi:

2>/dev/null ở ngữ cảnh gate / validation / SQL query.
|| true sau lệnh thay đổi trạng thái.
set +e không có cặp set -e kèm comment lý do.

§4.1.1 Annotation exception bắt buộc

Chỉ cho phép ngoại lệ nếu có marker comment ngay phía trên:

# silent-fail-allow: probe-only
# silent-fail-allow: cleanup
# errexit-allow: bounded-capture

Suppress stderr hợp lệ phải redirect vào biến/log có tên; không được nuốt câm hoàn toàn.

§4.1.2 Scanner 3 mức

critical: pattern đi kèm psql, DML/DDL, file write, gate logic → auto tạo APR fix_repair_dot.
warning: pattern probe-only chưa có marker → ghi system_issues, không auto-APR.
allow: có marker hợp lệ → skip.

§4.1.3 Coalesce issues parent/child

Scanner batch cùng session phải gộp issue theo coalesce_key:

issue đầu nhóm = parent (parent_issue_id IS NULL)
issue còn lại trỏ parent_issue_id về parent

Mục tiêu: không tạo 13 issue rời cho cùng một pattern hàng loạt.

§4.2 DOT cặp cho silent-fail (§4.1)

dot-ops-silent-fail-scan (A-tier): cron daily, quét ops-code/ theo registry/config.
dot-ops-silent-fail-propose (B/pseudo): tạo APR suggestion, không auto-fix toàn diện bằng regex rewrite trừ mẫu cực chắc chắn.

§4.3 Hạ tầng Health Check toàn hệ thống (★ S178 Fix 24)

Đ22 là SSOT cho toàn bộ hạ tầng health check hệ thống. Mỗi luật chuyên môn INSERT nội dung check vào bảng này; Đ22 sở hữu bảng + generic executor.

Căn cứ: §5 Triết lý 2 Động cơ = nền tảng cho MỌI health check. Đ37 §4.12 (SSOT nội dung luật). Đ37 §4.13 (trang bị đủ công cụ).

Schema — system_health_checks (DB directus, schema public):

CREATE TABLE system_health_checks (
  code TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  jurisdiction TEXT NOT NULL REFERENCES normative_registry(code),
  check_kind TEXT NOT NULL DEFAULT 'detect_only'
    CHECK (check_kind IN ('detect_only','detect_and_fix','verify_only')),
  executor_type TEXT NOT NULL CHECK (executor_type IN ('builtin','sql','function')),
  executor_ref TEXT NOT NULL,
  threshold_config JSONB NOT NULL DEFAULT '{}',
  severity_on_fail TEXT NOT NULL CHECK (severity_on_fail IN ('warn','critical')),
  auto_fix_action TEXT,
  is_active BOOLEAN NOT NULL DEFAULT true,
  order_index INT NOT NULL,
  description TEXT,
  _dot_origin TEXT NOT NULL DEFAULT 'unknown',
  CONSTRAINT chk_sql_executor_path CHECK (
    executor_type != 'sql' OR executor_ref LIKE 'knowledge__current-state__queries__%'
  ),
  CONSTRAINT chk_kind_fix_consistency CHECK (
    (check_kind = 'detect_and_fix' AND auto_fix_action IS NOT NULL)
    OR (check_kind IN ('detect_only','verify_only') AND auto_fix_action IS NULL)
  )
);

Cột chính:

jurisdiction — FK → normative_registry.code. Luật nào sở hữu nội dung check.
check_kind — detect_only (chỉ báo), detect_and_fix (tự sửa), verify_only (xác nhận sau fix).
auto_fix_action — NULL khi detect_only/verify_only. Có giá trị khi detect_and_fix.

Generic executor: Giữ nguyên pattern Đ43 §5.8 cũ — 5 guard security cho SQL executor (path whitelist, token blocker, readonly role, READ ONLY TX, timeout 30s). Kết quả chạy → system_issues (KHÔNG lưu trên bảng definition — NT1 tách definition vs runtime).

Chi tiết triển khai: Xem phụ lục reports/phu-luc-trien-khai-du-thao-ssot-hc-fix24.md Appendix A + B.

§4.4 HC-TRIGGER — Enforcement Gap Detection (★ S178 Fix 24)

Đ22 tự phát hiện + tự sửa khi enforcement mechanism bị thiếu trên bảng governed.

Bối cảnh: Trigger fn_description_birth_guard() (SSOT tại Đ4 §2.1) phải gắn cho MỌI bảng governed (theo Đ29 collection_registry.governance_role) có cột description. Nếu agent quên gắn → enforcement hở → vi phạm NT2+NT5+NT12.

Detect query (PG native — NT13, NT11):

SELECT cr.collection_name
FROM collection_registry cr
JOIN information_schema.columns c
  ON c.table_name = cr.collection_name
  AND c.column_name = 'description'
  AND c.table_schema = 'public'
WHERE cr.governance_role = 'governed'
  AND c.table_name IN (
    SELECT table_name FROM information_schema.tables
    WHERE table_schema = 'public' AND table_type = 'BASE TABLE'
  )
  AND cr.collection_name NOT IN (
    SELECT DISTINCT event_object_table
    FROM information_schema.triggers
    WHERE trigger_name LIKE 'trg_desc_guard_%'
      AND trigger_schema = 'public'
  );

7 guards cho auto-attach:

Function exists: CHỈ attach fn_description_birth_guard ĐÃ TỒN TẠI. Chưa có → DỪNG + escalate CRITICAL.
Config gate: dot_config.hc_trigger_autofix_enabled = 'true'. Default 'false'. Chuyển 'true' sau verify manual lần đầu.
Idempotency: Check pg_trigger trước khi CREATE. Chạy lặp không duplicate.
Lock timeout: SET LOCAL lock_timeout = '5s'. Timeout → skip bảng đó, retry next cycle.
Exclude scope: Chỉ BASE TABLE. Bỏ qua views, foreign tables, partition children, materialized views.
Post-attach verify: Query lại information_schema.triggers xác nhận trigger hiện diện + đúng function. Fail → ghi system_issues CRITICAL.
Audit trail: Ghi admin_fallback_log + system_issues INFO mỗi lần auto-attach thành công.

Seed row:

INSERT INTO system_health_checks VALUES
  ('HC-TRIGGER', 'Enforcement gap — trigger Đ4 chưa gắn',
   'LAW-22', 'detect_and_fix', 'sql',
   'knowledge__current-state__queries__hc-trigger-enforcement-gap.sql',
   '{}', 'critical', 'auto_attach_trigger',
   true, 100,
   'Quét bảng governed có cột description nhưng thiếu trg_desc_guard. Auto-attach với 7 guard.',
   'dieu22_fix24');

Chi tiết triển khai: Xem phụ lục reports/phu-luc-trien-khai-du-thao-ssot-hc-fix24.md Appendix A (SQL đầy đủ, pseudocode, fail path).

§4.5 Retrofit clause

14 ngày: remediation 13 DOT legacy Đ38 có silent-fail pattern đã inventory hoá.
30 ngày: paired test retrofit cho nhóm DOT lõi (nrm-*, apr-*, dot-dot-*).
90 ngày: paired test retrofit cho DOT canonical legacy còn lại.

Trong thời gian chờ 90 ngày, mọi fix mới theo fix_repair_dot phải có test hồi quy tối thiểu cho bug đang sửa.

§5. Triết lý 2 Động cơ

DOT kiểm tra = nhiệt kế, không phải thuốc.
DOT kiểm tra phải làm việc = hệ thống đang hỏng = phải sửa gốc.
Mục tiêu: DOT kiểm tra IDLE = thiết kế tốt.
Enforcement gap = rule rõ + auto-fix an toàn → Đ22 PHẢI tự sửa, không chờ agent nhớ.
Đ22 sở hữu hạ tầng system_health_checks — mỗi luật chuyên môn chỉ INSERT nội dung check (Đ37 §4.12+§4.13).

§6. Áp dụng Tầng 4 (mở rộng)

Cùng cơ chế áp dụng cho quy trình nghiệp vụ: đề xuất cải tiến, phản hồi khách hàng, cải tiến vận hành → vào system_issues/APR/task theo mức rõ ràng của rule.

§7. Thước đo

Mọi vấn đề tự phát hiện trước khi người dùng thấy.
≥50% lỗi rõ ràng tự sửa không cần người.
Pattern lặp lại → tự sinh đề xuất cải tiến.

CHANGELOG

Version	Nội dung
v1.0	Luật gốc: vòng lặp tự sửa, sổ kế toán kép, triết lý phơi bày vấn đề.
v1.1	S178 Fix 15 BAN HÀNH. Kỹ thuật hoá §4 bằng cấm silent-fail trong `ops-code/`, marker annotation, scanner 3 mức, coalesce parent/child, DOT cặp và retrofit 14/30/90 ngày.
v1.2	S178 Fix 24. +§4.3 Hạ tầng Health Check toàn hệ thống (bảng `system_health_checks`, generic executor, FK jurisdiction → normative_registry). +§4.4 HC-TRIGGER enforcement gap detection (7 guards, auto-attach). +§5 bổ sung triết lý. Nhận ownership hạ tầng HC từ Đ43 (Đ37 §4.12 SSOT nội dung luật). Council 2 vòng APPROVED (Gemini 9.8 + GPT 9.7). NT14 soi: phụ lục triển khai Appendix A+B.
v1.2 Fix 29	S178 Fix 29 sửa chui. +§1.1 Vòng đời Issue auto-close PG-native. Bước ④ vi phạm NT14 từ v1.0. Bổ sung: 5 cases đầy đủ (insert/idempotent/reopen/auto-close/noop), matching key composite (NT1 SSOT + Đ14), success gate (NT9), schema +resolved_at/resolved_by/reopen_count, config hc_auto_close_enabled. Reopen thay vì tạo mới (NT1 — 1 entity + 1 check = 1 issue duy nhất).

Điều 22 v1.2 BAN HÀNH | Sửa chui S178 Fix 29 +§1.1 Issue Lifecycle auto-close