Feat/req 000002 onboarding crosslink

.agents/skills/onboarding/SKILL.md

@@ -144,6 +144,10 @@ Create/update `docs/project_overview.md` for future agents.
 10. Risks and Unknowns
 11. Recommendations for Future Agents
 12. Evidence Index (files read)
+13. Knowledge Base & Feature Specs:
+    - Chỉ điểm rõ ràng nơi lưu trữ toàn bộ tài liệu chi tiết về tính năng (Spec Packages) của project này.
+    - Nếu `.agents/configs/spec_config.json` có `override: true` và đường dẫn hợp lệ: chỉ định đường dẫn ngoài repo là `<path>/<project>/tasks/REQ-*` (theo hợp đồng § 5.9).
+    - Nếu `override: false` (mặc định): chỉ định đường dẫn nội bộ repo là `docs/tasks/REQ-*`.
 
 Larger repos: add communication, data, API, security when evidenced.
 
@@ -172,7 +176,7 @@ Keep it short:
 - [ ] spec_config.json project identifier configured (or preserved if already set)
 - [ ] `AGENTS.md` filled with project context
 - [ ] Agent-specific context file created/updated **only for current agent** (Claude → `CLAUDE.md`, Gemini → `GEMINI.md`, Cursor → rules only)
-- [ ] `docs/project_overview.md` created/updated (**Vietnamese**)
+- [ ] `docs/project_overview.md` created/updated (**Vietnamese**, includes Knowledge Base & Feature Specs cross-link)
 - [ ] No artifacts outside the current repo; no context files for other agents
 - [ ] User knows how to start the next REQ (natural language or slash override)
 

CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.2.1] - 2026-09-10
+
+Onboarding Knowledge Base Cross-linking — Bổ sung chỉ dẫn liên kết chéo "Knowledge Base & Feature Specs" vào tài liệu tổng quan repository (`docs/project_overview.md`) khi thực hiện onboarding.
+
+### Changed
+- **`onboarding` skill (`.agents/skills/onboarding/SKILL.md`)**:
+  - Thêm mục `13. Knowledge Base & Feature Specs` vào cấu trúc tối thiểu trong Phase D (`docs/project_overview.md`).
+  - Hướng dẫn chỉ rõ vị trí lưu trữ toàn bộ tài liệu đặc tả tính năng (Spec Packages) của project dựa trên cấu hình `spec_config.json` (`<path>/<project>/tasks/REQ-*` khi `override: true`, hoặc `docs/tasks/REQ-*` khi `override: false`).
+  - Cập nhật checklist kiểm tra tại Phase E / Output checklist.
+
+### Added
+- **Release notes**: Bổ sung tài liệu phát hành chi tiết tại `release-notes/4.2.1.md`.
+
 ## [4.2.0] - 2026-09-10
 
 Centralized Spec Package Knowledge Base via `spec_config.json` Override Path — hỗ trợ chuyển hướng lưu trữ toàn bộ tài liệu Spec Package sang kho tri thức tập trung bên ngoài repository theo cấu trúc `<path>/<project>/tasks/REQ-*`.

docs/tasks/REQ-000002-onboarding-crosslink/acceptance.md

@@ -0,0 +1,11 @@
+# Acceptance Criteria
+
+## 1. Kiểm tra nội dung (Review)
+- File `.agents/skills/onboarding/SKILL.md` đã được chỉnh sửa.
+- Trong phần `Phase D`, danh sách cấu trúc tối thiểu có mục "13. Knowledge Base & Feature Specs".
+
+## 2. Kiểm tra tính toàn vẹn (Integrity)
+- File `.agents/skills/onboarding/SKILL.md` vẫn giữ nguyên các cấu trúc khác, định dạng Markdown hợp lệ.
+
+## 3. Kết quả mong đợi
+- Lần tới khi chạy skill onboarding, file `project_overview.md` được sinh ra sẽ có thêm mục nói về Knowledge Base & Feature Specs.

docs/tasks/REQ-000002-onboarding-crosslink/analysis.md

@@ -0,0 +1,52 @@
+# Analysis
+
+## Metadata
+- **Request ID:** REQ-000002
+- **Title:** Bổ sung Cross-link vào docs/project_overview.md cục bộ khi thực hiện onboarding projects
+- **Target File:** `.agents/skills/onboarding/SKILL.md` (Phase D)
+
+## Problem Analysis
+Hiện tại, khi một dự án được onboard, quy trình sẽ tạo ra file `docs/project_overview.md`. Tuy nhiên, file này không chứa thông tin chỉ dẫn nơi lưu trữ các tài liệu đặc tả tính năng (Spec Packages - các `REQ-*`). Hệ quả là Developer hoặc Agent mới khi tiếp cận repository sẽ khó khăn trong việc tìm kiếm các chức năng hiện có của dự án. 
+
+## Current State
+Trong file `.agents/skills/onboarding/SKILL.md` (Phase D), cấu trúc tối thiểu cho `docs/project_overview.md` bao gồm 12 mục chính (từ Executive Summary đến Evidence Index), không có mục nào đề cập đến đường dẫn hoặc cách thức tìm Spec Packages.
+
+## Business Impact
+- **Tăng cường trải nghiệm Developer (DX) và Agent (AX):** Người và máy đều dễ dàng tra cứu tài liệu và quy trình ngay khi tiếp cận dự án.
+- **Tiết kiệm thời gian:** Định hướng rõ ràng ngay từ file tổng quan giúp tiết kiệm thời gian điều hướng repository.
+
+## Technical Impact
+- **Scope thay đổi:** Cần sửa file `.agents/skills/onboarding/SKILL.md`, phần "Phase D — Knowledge base `docs/project_overview.md`".
+- Bổ sung một mục có tên "Knowledge Base & Feature Specs" vào danh sách cấu trúc tối thiểu (có thể là mục thứ 13).
+- Cung cấp chỉ điểm rõ ràng trong `docs/project_overview.md` để báo cho người dùng biết "Toàn bộ tài liệu chi tiết về tính năng của project này đang được lưu ở đâu" (dựa trên `spec_config.json` nếu có, hoặc mặc định trong thư mục repo).
+
+## Data Impact
+Không có.
+
+## Security Impact
+Không có.
+
+## Operational Impact
+Tạo ra `project_overview.md` đầy đủ ngữ cảnh hơn, giúp bảo trì và phát triển tính năng trong các REQ sau này trơn tru hơn.
+
+## Dependencies
+- Phụ thuộc vào kiến trúc hiện tại của `project_overview.md` được định nghĩa trong `onboarding/SKILL.md`.
+
+## Constraints
+- Không làm phá vỡ cấu trúc hiện tại của `onboarding/SKILL.md`.
+
+## Risks
+Rủi ro (Low): Thay đổi này rất nhỏ và hoàn toàn nằm ở khía cạnh tài liệu hóa.
+
+## Options Requiring ADR
+Không có. Thay đổi nhỏ, rõ ràng.
+
+## Recommended Direction
+Bổ sung hạng mục mới "13. Knowledge Base & Feature Specs" vào cấu trúc tối thiểu trong Phase D của `.agents/skills/onboarding/SKILL.md`. 
+
+## Open Blockers
+Không có.
+
+## Analysis Result
+- **Risk:** low
+- **ADR Recommendation:** ADR_NOT_REQUIRED

docs/tasks/REQ-000002-onboarding-crosslink/design.md

@@ -0,0 +1,13 @@
+# Technical Design
+
+## 1. Quyết định kiến trúc (Architecture Decisions)
+- **ADR**: Không yêu cầu (ADR_NOT_REQUIRED). Sự thay đổi chỉ ở mức độ cập nhật văn bản hướng dẫn/prompt cho Agent, không thay đổi luồng hệ thống hay kiến trúc phần mềm nào.
+
+## 2. Thiết kế chi tiết
+- **Target File**: `.agents/skills/onboarding/SKILL.md`
+- **Vị trí sửa đổi**: Tìm kiếm phần `# Phase D — Knowledge base docs/project_overview.md` trong file.
+- **Nội dung thay đổi cụ thể**: Cập nhật danh sách "The resulting file must include at minimum the following sections:" để bổ sung thêm phần số 13.
+  - `13. Knowledge Base & Feature Specs: Chỉ dẫn nơi lưu trữ tài liệu đặc tả (Spec Packages - REQ-*).`
+
+## 3. Tác động hệ thống
+- Skill onboarding sẽ sử dụng danh sách này làm hướng dẫn để sinh ra file `project_overview.md`. Khi danh sách được cập nhật, file kết quả cũng sẽ tự động mang theo thông tin về nơi lưu tài liệu.

docs/tasks/REQ-000002-onboarding-crosslink/manifest.yaml

@@ -0,0 +1,74 @@
+schema_version: 1
+
+id: REQ-000002
+slug: onboarding-crosslink
+title: Bổ sung Cross-link vào docs/project_overview.md
+risk: low
+status: done
+
+artifacts:
+  raw: raw.md
+  analysis: analysis.md
+  requirements: requirements.md
+  design: design.md
+  tasks: tasks.md
+  acceptance: acceptance.md
+  spec_review: spec-review.md
+
+decisions: []
+
+validation:
+  status: passed
+  reviewed_at: null
+  blockers: []
+  warnings: []
+
+approval:
+  spec_package:
+    status: approved
+    approved_by: user
+    approved_at: "2026-09-10T16:11:44Z"
+  develop:
+    status: not_required
+    approved_by: null
+    approved_at: null
+  user_review:
+    status: approved
+    approved_by: user
+    approved_at: "2026-09-10T16:32:08Z"
+  deploy:
+    status: pending
+    approved_by: null
+    approved_at: null
+
+execution:
+  current_task: null
+  completed_tasks:
+    - TASK-001
+  blocked_tasks: []
+  attempts:
+    TASK-001: 1
+  last_activity_at: "2026-09-10T16:22:59Z"
+  last_activity_by: release_manager
+
+review:
+  status: passed
+  current_task: TASK-001
+  blockers: []
+  warnings: []
+  reviewed_at: "2026-09-10T16:20:52Z"
+
+qa:
+  unit_test: passed
+  system_test: passed
+  uat: passed
+  converge: passed
+  attempts: 1
+  blockers: []
+  last_run_at: "2026-09-10T16:25:30Z"
+
+git:
+  working_branch: feat/REQ-000002-onboarding-crosslink
+  branch_guard_status: done
+  commits:
+    TASK-001: 14d5f27

docs/tasks/REQ-000002-onboarding-crosslink/qa/converge-report.md

@@ -0,0 +1,95 @@
+# Convergence Report
+
+> When filled: write the body in **Vietnamese**. Keep result tokens in English.  
+> Path: `docs/tasks/REQ-000002-onboarding-crosslink/qa/converge-report.md`  
+> Runs only after QA PASSED. Does **not** mark package `done` or deploy.
+
+## Metadata
+
+- REQ ID: REQ-000002
+- Package: docs/tasks/REQ-000002-onboarding-crosslink/
+- Reviewer: Release Manager
+- Converged at: 2026-09-10T23:28:00+07:00
+
+## Result
+
+- Result: PASSED
+- Blocking Issues: 0
+
+## Requirement Coverage
+
+| Requirement | Implemented? | Evidence |
+|---|---|---|
+| REQ-000002 Yêu cầu 1 (Nghiệp vụ: Bổ sung chỉ dẫn Spec Packages vào `docs/project_overview.md`) | yes | Git commit `14d5f27`, UT-001, ST-001, ST-002, UAT-001 |
+| REQ-000002 Yêu cầu 2 (Kỹ thuật: Sửa `onboarding/SKILL.md` Phase D mục 13 theo `spec_config.json`) | yes | Git commit `14d5f27`, UT-001, ST-001, ST-002, TASK-001-code-review.md |
+| REQ-000002 Ràng buộc 3 (Không thay đổi logic/cấu trúc các Phase khác, giữ chuẩn Markdown) | yes | UT-002, UT-003 (`validate-all.js` PASS 9/9 bước), TASK-001-code-review.md |
+
+## Design Coverage
+
+| Design ID | Implemented? | Evidence |
+|---|---|---|
+| REQ-000002 Design Section (Cập nhật Phase D và Output checklist trong `.agents/skills/onboarding/SKILL.md`) | yes | Git commit `14d5f27`, diff tại `.agents/skills/onboarding/SKILL.md:L147-151,L179` |
+| ADR_NOT_REQUIRED (Cập nhật văn bản hướng dẫn/prompt, không tác động kiến trúc) | yes | Xác nhận trong `design.md`, `TASK-001-code-review.md` |
+
+## Task Completion
+
+| Task | Status | Review | Notes |
+|---|---|---|---|
+| TASK-001 | done | PASSED | Commit `14d5f27` đã được review và kiểm chứng, kết quả PASSED không có blocker hay cảnh báo |
+
+## Acceptance Coverage
+
+| Acceptance / Test ID | Evidence | Result |
+|---|---|---|
+| AC-001 (Kiểm tra nội dung: Phase D có mục 13 "Knowledge Base & Feature Specs") | UT-001, ST-001, ST-002, `TASK-001-code-review.md` | PASSED |
+| AC-002 (Kiểm tra tính toàn vẹn: Cấu trúc file nguyên vẹn, Markdown hợp lệ) | UT-002, UT-003, `TASK-001-code-review.md` | PASSED |
+| Mục 3 - Kết quả mong đợi (Giá trị thực tế cho Developer & Agent mới) | UAT-001, UAT-002, `qa/uat-report.md` | PASSED |
+
+## Review Evidence
+
+- All required task reviews PASSED: yes
+  - `reviews/TASK-001-code-review.md`: PASSED (0 blocker, 0 major, 0 minor, 0 warning)
+
+## QA Evidence
+
+- QA summary PASSED: yes
+- Reports present:
+  - `qa/qa-summary.md` (Overall Result: PASSED)
+  - `qa/unit-test-report.md` (3/3 test cases PASSED: UT-001, UT-002, UT-003)
+  - `qa/system-test-report.md` (2/2 scenarios PASSED: ST-001, ST-002)
+  - `qa/uat-report.md` (2/2 scenarios PASSED: UAT-001, UAT-002)
+
+## Scope Consistency
+
+- Phạm vi tệp kỳ vọng (Expected File Scope): `.agents/skills/onboarding/SKILL.md`
+- Phạm vi tệp thực tế trong commit `14d5f27`: Duy nhất 1 file `.agents/skills/onboarding/SKILL.md` (+5 lines, -1 line).
+- Không có bất kỳ file nào nằm ngoài phạm vi được sửa đổi hoặc commit.
+
+## Package-Code Drift
+
+- Drift found: none
+- Toàn bộ nội dung triển khai khớp 100% với đặc tả yêu cầu, thiết kế và tiêu chí nghiệm thu.
+
+## Manifest Consistency
+
+- Manifest matches reality: yes
+  - Trạng thái gói (`status`): `converging`
+  - Các tác vụ hoàn thành (`execution.completed_tasks`): `TASK-001`
+  - Commit tương ứng (`git.commits.TASK-001`): `14d5f27`
+  - Trạng thái kiểm thử (`qa`): `unit_test: passed`, `system_test: passed`, `uat: passed`, `converge: in_progress`
+
+## Blocking Issues
+
+Không có.
+
+## Warnings
+
+Không có.
+
+## Corrections Applied
+
+- None (Tất cả tài liệu, cấu hình và mã nguồn đã hoàn toàn nhất quán).
+
+## Final Decision
+
+- **PASSED** → Sẵn sàng bàn giao cho Project Manager để cập nhật `manifest.yaml` sang trạng thái `awaiting_user_review` và yêu cầu xác nhận phê duyệt từ người dùng (`APPROVED_USER_REVIEW`).

docs/tasks/REQ-000002-onboarding-crosslink/qa/qa-summary.md

@@ -0,0 +1,62 @@
+# QA Summary
+
+> When filled: write the body in **Vietnamese**. Keep result tokens in English.  
+> Path: `docs/tasks/REQ-000002-onboarding-crosslink/qa/qa-summary.md`  
+> Driven by `acceptance.md`. Max auto-fix attempts: **3**.
+
+## Metadata
+
+- REQ ID: REQ-000002
+- Package: docs/tasks/REQ-000002-onboarding-crosslink/
+- Attempt: 1
+- Started at: 2026-09-10T23:24:00+07:00
+- Finished at: 2026-09-10T23:26:30+07:00
+
+## Overall Result
+
+- Result: PASSED
+- Failure class: none
+
+## Unit Test
+
+- Status: PASSED
+- Report: `qa/unit-test-report.md`
+- Notes: Xác nhận nội dung mục 13 "Knowledge Base & Feature Specs" trong Phase D của `.agents/skills/onboarding/SKILL.md` và kiểm tra tính toàn vẹn cú pháp Markdown đạt 100%. Bộ kiểm thử tự động `validate-all.js` vượt qua toàn bộ 9/9 bước kiểm tra.
+
+## System Test
+
+- Status: PASSED
+- Report: `qa/system-test-report.md`
+- Notes: Xác nhận tính tương thích của hướng dẫn Onboarding với cả 2 trường hợp `override: false` (nội bộ repo `docs/tasks/REQ-*`) và `override: true` (ngoài repo `<path>/<project>/tasks/REQ-*`) tuân thủ Contract § 5.9.
+
+## UAT
+
+- Status: PASSED
+- Report: `qa/uat-report.md`
+- Notes: Xác nhận giá trị thực tế cho lập trình viên và AI Agent mới tiếp cận dự án, dễ dàng định vị tài liệu đặc tả tính năng qua `docs/project_overview.md`.
+
+## Performance
+
+- Status: NOT_REQUIRED
+- Report: qa/performance-report.md (if applicable)
+
+## Security
+
+- Status: NOT_REQUIRED
+- Report: qa/security-report.md (if applicable)
+
+## Failed Items
+
+| ID | Type | Linked Requirement | Evidence | Class |
+|---|---|---|---|---|
+| Không có | N/A | N/A | Không có lỗi phát sinh | N/A |
+
+## Auto-loop Attempt
+
+- Current attempt: 1
+- Max attempts: 3
+- Next route: none
+
+## Final Result
+
+- Ready for converge: yes