Vì sao tôi gộp 2 initiative thành 1 portfolio + N project — và 11 phase audit để ship sạch 185 file rename

TL;DR

• 2 initiative peer-level (coarising_agile cho entity + jarvis_v2 cho tool) làm tôi rối daily entry point — sáng không biết bám file nào.
• Deep research PMI Portfolio Management + Linear/Asana hierarchy + OKR Cascade đều converge cùng pattern: 1 portfolio → N project → sprint cycles.
• Quyết định Path 1 (Full restructure NOW) thay vì Path 2 (incremental). Hỗn loạn folder layer cao = càng để lâu càng đắt.
• 11 phase audit ship 185 file rename giữ git history qua git mv + sed batch 90+ file path ref + 7 README mới + knowledge graph revalidate. 0 stale path còn lại.

Mở đầu — Câu hỏi đơn giản tôi không trả lời được

Tối hôm qua tôi hỏi JARVIS:

“Hằng ngày anh bám trên cái gì để làm việc cho hiệu quả?”

Câu trả lời em đưa ra: 5 file ở 4 location khác nhau. coarising_agile/CURRENT_STATE.md cho daily routine, jarvis_v2/05_execution/sprints/sprint_NN.md cho infra task, knowledge/personal/LIFE_VISION_10Y.md cho strategic context, CLAUDE.md cho bootstrap rule, streams/0N_*.md cho stream-specific work.

Đọc xong tôi nói: “C vẫn cứ rối rối nhỉ?”

Vấn đề không phải file nào sai. Vấn đề là 2 initiative peer-level trong cùng brain/initiatives/ — không có thằng nào điều phối thằng nào. Daily routine bị split. AI cũng không biết auto-load file nào trước.

Vấn đề — 2 initiative cùng layer = không ai là root

Cấu trúc trước:

brain/initiatives/
├── coarising_agile/   (entity coordination plane, N streams song song)
│   ├── CURRENT_STATE.md
│   ├── README.md, 2026_q3/, streams/
│   └── ...
└── jarvis_v2/          (tool layer infra, ADR + sprint + design)
    ├── 02_strategic/
    ├── 03_design/adr/
    ├── 05_execution/sprints/
    └── ...

Trên giấy clean — entity coordination tách khỏi tool layer. Thực tế:

• Sáng mở terminal: bám file nào? CURRENT_STATE.md của coordination hay sprint_05.md của tool layer?
• AI auto-load: load cả 2 hay chỉ 1? Nếu chỉ 1 thì bỏ sót context.
• Cross-folder name collision: 1 keyword tồn tại ở 2 folder với 2 nghĩa khác nhau. Mention keyword đó trong daily standup — context nào?

Tôi push back JARVIS: “Thông thường người ta quản lý đa nguồn, đa thực thể này sao cho hiệu quả? Em deep research giúp anh.”

Research — 3 framework converge cùng 1 pattern

Em research 3 framework công nghiệp:

1. PMI Portfolio Management

PMI (Project Management Institute) chuẩn:

• Portfolio = collection of programs + projects + operations để đạt strategic goal
• Program = related projects coordinated together
• Project = temporary endeavor producing unique deliverable
• Operations = ongoing repeatable work

Pattern: 1 portfolio → N program/project → sprint/iteration.

Initiative-level coordination plane CÓ trong PMI. 2 initiative peer-level KHÔNG có trong PMI — sẽ là 2 portfolio = require strategic alignment ở layer cao hơn (enterprise level).

2. Linear / Asana Hierarchy

Tool công nghiệp 2020+:

• Workspace → Team/Project → Issue/Task
• Linear thêm Cycle (sprint) song song Issue
• Asana thêm Portfolio group multiple Project

Pattern: 1 workspace → N project → cycle/sprint.

Tôi bám pattern Linear vì nó closest với cách AI partner đọc filesystem.

3. OKR Cascade with Business Goals layer

Andy Grove → John Doerr:

• Mission (eternal) → Vision (3-10y) → Business Goal (yearly) → OKR (quarterly) → Initiative/Project (sprint)

Pattern: 1 mission → N vision/goal → N OKR → N project.

Initiative-level = OKR layer. Project-level = below OKR. KHÔNG có “2 initiative same level coordinating each other”.

Insight — 3 framework converge

Cả 3 đều cùng 1 nguyên tắc:

Có duy nhất 1 layer điều phối ở mỗi tầng. Multiple peer = không ai là root = chaos.

Áp vào folder của tôi: gộp coarising_agile + jarvis_v2 thành 1 portfolio, coi jarvis_v2 là 1 project Tier 1 (infra), các stream là sibling project Tier 2 (entity).

Decision matrix — 3 path

JARVIS đưa 3 lựa chọn:

Path	Action	Risk	Cost
1	Full restructure NOW — collapse 2 → 1 portfolio × N project	Mid (đụng 90+ file path ref)	1 buổi audit
2	Incremental — keep 2 initiative, add coordinator README link cross-ref	Low	30 phút
3	Defer — sprint sau xét lại	Zero	0

Path 2 dễ nhất nhưng kick can down the road. Path 3 là không làm gì.

Tôi chọn Path 1. Lý do: hỗn loạn folder layer cao = càng để lâu càng đắt. Hôm nay sed batch fix 90 file. 3 tháng nữa = sed batch + 50 link đã đẻ ra + memory đã reference path cũ. Audit tốt hơn ăn nợ kỹ thuật.

Đặt câu lệnh cho em:

“Full restructure bây giờ luôn, nhưng nhớ deep audit, deep work, làm chậm mà chắc, cẩn thận và tỉ mỉ, research, search kỹ.”

Execution — 11 phase audit

Em chia 11 phase, từng phase verify trước khi qua phase tiếp:

Phase	Action	Output
0	Pre-flight audit — count file affected	109 file path ref + 9 memory + 2 cron path
1	Create _portfolio skeleton	31 thư mục mới
2	git mv jarvis_v2 → _portfolio/projects/jarvis_tool	History preserve qua git rename detection
3	Sed batch update 90+ file path ref	brain/initiatives/jarvis_v2 → brain/initiatives/_portfolio/projects/jarvis_tool
4	Knowledge graph entities.yaml + edges.yaml refresh	61 entity + 81 edge canonical_doc paths updated
5	Memory files 7 update	~/.claude/projects/.../memory/*.md path ref
6	Create N sibling project README	1 README per Tier 2 entity stream
7	Rename CURRENT_STATE.md → DASHBOARD.md + upgrade aggregate content	Dashboard portfolio snapshot
8	Update nested CLAUDE.md (jarvis_tool/CLAUDE.md, .agents/skills/CLAUDE.md)	Path ref + folder structure example refresh
9	Test critical paths — age vault, skill discovery, KG query, canonical_doc validity	5/5 pass
10	Git commit + push	Commit hash hiện trên gitlab

After:

brain/initiatives/_portfolio/
├── DASHBOARD.md           ← PRIMARY DAILY ENTRY POINT
├── README.md              ← philosophy + 2-tier overview
├── 2026_q3/sprint_NN/     ← active sprint (Tier 2 cycle)
├── streams/0N_*.md        ← stream continuous backlog
├── templates/
└── projects/              ← N project (1 tool + N stream)
    ├── tier1_infra/       ← Tier 1 INFRA (tool layer)
    ├── stream1/           ← Tier 2 entity stream
    ├── stream2/
    └── ...                ← additional stream per personal context

Bug encounter — 3 lần phải dừng audit verify

Bug 1 — sed batch initial fail vì xargs + tên file dài

Lần đầu chạy:

grep -rl "brain/initiatives/jarvis_v2" . | xargs sed -i '' 's/.../.../g'

Lỗi: “File name too long”. Bash for-loop concat filename quá ngưỡng. Fix qua while IFS= read -r file; do ... done pattern — process từng file 1 lần.

Bug 2 — pre-commit hook block 1 file pre-existing tech debt

Hook scan modified file phát hiện hardcoded /Users/danghongtien/Repository/JARVIS ở line 10 file promote.sh. Hardcoded path đã có từ trước, không phải thay đổi của tôi. Sed batch chỉ update line 6 (comment reference path) thôi.

Lựa chọn:

• (a) Bypass hook với --no-verify
• (b) Fix line 10 trong cùng commit (scope creep)
• (c) Unstage promote.sh, ship 184 file sạch, separate commit fix sau

Chọn (c). Lý do: Trace rule — mỗi dòng đổi PHẢI trace về request. Restructure commit purity > convenience. Sau commit chính, làm 1 commit fix promote.sh với SCRIPT_DIR fallback (hook recommended pattern). 2 commit, audit trail rõ.

Bug 3 — 3 broken markdown link sau commit

Test sau ship phát hiện 3 link sai:

• blog_dht_com/README.md → sites/CLAUDE.md (file thực tế là sites/danghongtien/CLAUDE.md)
• blog_dht_com/README.md → ../../jarvis_tool/03_design/plans/ (path tính sai 1 cấp, đúng là ../jarvis_tool/)
• 1 README → reference file _reference/<lib>.md (tôi tự bịa file không tồn tại)

Fix qua Edit tool, 3 link một lúc. Lesson: validate link sau ship cần script tự động không phải mắt người đọc.

Verify — 5 test critical pass sau ship

# 1. 0 stale path còn lại trong live file (trừ archive sessions/dreams)
grep -rln "brain/initiatives/jarvis_v2\|brain/initiatives/coarising_agile" . \
  --include="*.md" --include="*.py" --include="*.yaml" \
  | grep -v ".claude/projects/" | grep -v "workspace/sessions/" \
  | wc -l
# Output: 0

# 2. Knowledge graph parse cleanly
python3 -c "import yaml; e=yaml.safe_load(open('brain/graph/entities.yaml')); print(len(e))"
# Output: 61 entities

# 3. age vault decrypt OK
bash workspace/aae_core/security/age-cat.sh openai_api_key | head -1
# Output: OPENAI API KEY (created 2026-04-24, ...)

# 4. Skill discovery
ls .claude/skills/ | wc -l
# Output: 51 skill loaded

# 5. canonical_doc paths valid
test -f brain/initiatives/_portfolio/projects/jarvis_tool/05_execution/sprints/sprint_05.md \
  && echo "sprint_05.md exists"
# Output: sprint_05.md exists

5/5 pass. Restructure clean.

Outcome — 5 commit ship, 0 stale path

Ngày làm việc end với 5 commit ship lên main:

Commit	Scope	File
1	refactor(portfolio): Path 1 Full Restructure	184 file (rename + sed batch + 7 README mới + DASHBOARD upgrade)
2	chore(persistence): memory + observability + precompact	7 file
3	chore(boq-016): drawing index manifest	2 file
4	fix(promote): SCRIPT_DIR fallback + path ref	1 file
5	chore(obsidian): UI state refresh	2 file

Working tree clean. Daily entry point clear: brain/initiatives/_portfolio/DASHBOARD.md. AI auto-load 1 portfolio thay vì split 2 initiative. Stream backlog nguyên vẹn. Sprint 01 IN_PROGRESS với task Tier 1 + stream action Tier 2.

Lesson — Folder structure không phải cosmetic

Trước session này tôi nghĩ folder structure là cosmetic — clean nice but optional. Sau audit này tôi đổi ý:

Folder structure layer cao là một dạng decision encoded vào filesystem. Mỗi cấp folder = một câu hỏi ‘thằng nào điều phối thằng nào’. Sai là chaos lan downstream.

3 framework PMI/Linear/OKR converge cùng 1 pattern KHÔNG phải ngẫu nhiên. Pattern này encode 50+ năm kinh nghiệm coordination team người. AI partner đọc filesystem cũng cần 1 root điều phối, không phải 2 peer.

Bài học operational:

• Khi câu hỏi đơn giản “hằng ngày tôi bám gì” không có câu trả lời 1 dòng — folder structure đang sai.
• Hỗn loạn folder layer cao = càng để lâu càng đắt. Sed batch fix tốn 1 buổi, ăn nợ 3 tháng = sed batch + 50 link đã đẻ ra.
• Audit kỹ trước commit > sửa lặt vặt sau commit. 11 phase trước commit = 5 test pass sau commit. Phép lạ không có.
• Pre-commit hook block tech debt pre-existing = signal, không phải obstacle. Bypass = vi phạm Trace rule. Fix root cause + separate commit = audit trail rõ.

Tomorrow Sprint 01 Day 2: skill SKILL.md migrate entity_context_required + tr_alignment + pillar_focus field cho 25 skill. Đó là Tier 1 task tiếp theo trong cycle Q3.

Daily entry point hôm nay đã clean. Câu hỏi “anh bám gì” có 1 câu trả lời.