viepilot 1.9.4 → 1.9.7

package/CHANGELOG.md

@@ -19,6 +19,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - None yet.
 
+## [1.9.7] - 2026-04-02
+
+### Fixed
+
+- **ENH-024**: Fix chuỗi truyền tải ui-direction bị đứt qua crystallize → vp-auto:
+  - `crystallize.md` Step 1A: đổi trigger thành hard check mandatory khi `.viepilot/ui-direction/` exists (không còn soft heuristic "if indicates").
+  - `crystallize.md` Step 10: thêm "UI Direction context injection" — inject `context_required` trỏ vào `notes.md` + `style.css` + `pages/*.html` vào task files cho UI tasks.
+  - `autonomous.md` Step 3a: thêm "UI Direction safety check" — warn + auto-load latest session nếu UI task thiếu ui-direction trong context_required.
+  - `templates/project/AI-GUIDE.md`: thêm 2 rows ui-direction vào Quick Lookup table + footnote hướng dẫn resolve `{session}`.
+
+## [1.9.6] - 2026-04-02
+
+### Fixed
+
+- **ENH-023**: `workflows/autonomous.md` Step 3 Handle Result PASS — thêm `Update ROADMAP.md: sync phase progress % và task count nếu phase status/progress thay đổi` vào danh sách update sau `CHANGELOG.md`. Trước đây ROADMAP.md chỉ được sync tại phase-complete (Step 5a), bỏ sót task-level progress.
+
+## [1.9.5] - 2026-04-02
+
+### Added
+
+- **M1.29 / Phase 35 (ENH-022)** — Crystallize **Step 4** ghi thêm **`.viepilot/architecture/<diagram>.mermaid`** (raw Mermaid, mirror khối fenced trong `ARCHITECTURE.md`); bảng tên canonical + policy trong `workflows/crystallize.md`; template `templates/project/ARCHITECTURE.md` có **Diagram source files** và dòng path từng section; **vp-crystallize** 0.5.2, **vp-audit** 0.3.2; `docs/skills-reference.md`; `tests/unit/vp-enh022-crystallize-architecture-files-contracts.test.js` (**308** tests).
+
 ## [1.9.4] - 2026-04-02
 
 ### Fixed

package/README.md

@@ -2,15 +2,15 @@
 
 **Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**
 
-[![Version](https://img.shields.io/badge/version-1.9.4-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.9.5-blue.svg)](CHANGELOG.md)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-16-purple.svg)](#skills-reference)
 [![Workflows](https://img.shields.io/badge/workflows-12-orange.svg)](#workflows)
 [![Templates](https://img.shields.io/badge/templates-17-cyan.svg)](#templates)
-[![Tests](https://img.shields.io/badge/tests-304%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-308%20passing-brightgreen.svg)](tests/)
 [![GitHub](https://img.shields.io/github/stars/0-CODE/viepilot?style=social)](https://github.com/0-CODE/viepilot)
 
-**Versioning:** Shield **1.9.4** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**1.9.4**) is the Node package identifier for this repo; use the framework version for milestone releases and docs.
+**Versioning:** Shield **1.9.5** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**1.9.5**) is the Node package identifier for this repo; use the framework version for milestone releases and docs.
 
 ViePilot là bộ skill framework cho phép AI assistant (Claude, GPT, etc.) phát triển dự án một cách **tự động**, **có kiểm soát**, và **có thể khôi phục**. Thiết kế theo các tiêu chuẩn chuyên nghiệp: Semantic Versioning, Conventional Commits, Keep a Changelog.
 
@@ -28,12 +28,12 @@ Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
 
 | Chỉ số / Metric | Giá trị / Value |
 |-----------------|-----------------|
-| Total LOC | **~27,779+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
+| Total LOC | **~27,991+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
 | Skills | **16** |
 | Workflows | **12** |
 | Templates | **17** (Project: 12, Phase: 5) |
 | CLI Commands | **18** (`vp-tools` 17 subcommands + `viepilot` installer) |
-| Tests | **304** (15 suites: unit + integration + AI compat + README metrics + UI direction + ENH contracts + scope policy + FEAT-009 + FEAT-010 + ENH-021 routing + FEAT-001 Claude Code docs + viepilot-info/update/install) |
+| Tests | **308** (16 suites: unit + integration + AI compat + README metrics + UI direction + ENH contracts + scope policy + FEAT-009 + FEAT-010 + ENH-021 routing + FEAT-001 Claude Code + ENH-022 crystallize architecture files + viepilot-info/update/install) |
 | ViePilot phases (local `.viepilot`) | **34** phase cycles — **M1.29** FEAT-001 (**v1.9.3** doc); patch **v1.9.4** (Claude installer); **M1.28** FEAT-010 (**v1.9.1**); **v1.9.2** (ENH-019~021); **M1.27** (**v1.9.0** FEAT-009); xem `CHANGELOG.md` |
 | Standards | 5 (SemVer, Commits, Changelog, Comments, Contributors) |
 
@@ -393,7 +393,7 @@ viepilot/
 ├── bin/                           # CLI tools
 │   └── vp-tools.cjs               # 17 subcommands; uses ../lib/cli-shared.cjs, viepilot-info/update.cjs
 │
-├── tests/                         # Test suite (267 tests)
+├── tests/                         # Test suite (308 tests)
 │   ├── unit/                      # Unit tests
 │   │   ├── validators.test.js     # CLI subprocess + in-process coverage tests
 │   │   └── ai-provider-compat.test.js  # 142 AI compat tests

package/docs/skills-reference.md

@@ -78,6 +78,7 @@ Complete reference for all ViePilot skills.
 ├── AI-GUIDE.md
 ├── PROJECT-META.md
 ├── ARCHITECTURE.md
+├── architecture/   (*.mermaid diagram sidecars — ENH-022, mirror fenced blocks)
 ├── PROJECT-CONTEXT.md
 ├── SYSTEM-RULES.md
 ├── ROADMAP.md
@@ -427,6 +428,7 @@ CHANGELOG.md (updated)
 4. **CLI coverage** — mỗi command có documentation không
 5. **docs/ sync** — docs/ có match với thực tế (skills count, workflows count) không
 6. **ROOT drift** — README.md badges, ROADMAP.md status có up-to-date không
+7. **ENH-022 (architecture sidecars)** — khi matrix có Mermaid thực tế, gợi ý kiểm `.viepilot/architecture/<type>.mermaid` khớp `ARCHITECTURE.md`
 
 ### Output
 - Audit report với danh sách gaps

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "1.9.4",
+  "version": "1.9.7",
   "description": "**Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**",
   "main": "index.js",
   "bin": {

package/skills/vp-audit/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-audit
 description: "Audit state, docs drift, and stack best-practice compliance — works on any project"
-version: 0.3.1
+version: 0.3.2
 ---
 
 <cursor_skill_adapter>
@@ -49,6 +49,7 @@ Auto-detect nếu đang chạy trong viepilot framework repo để thêm framewo
   - `required` diagrams must have Mermaid content
   - `optional` diagrams may be omitted/merged with explicit note
   - `N/A` diagrams must have rationale line
+- **ENH-022 (recommended check):** when a diagram type is `required` (or `optional` with a real Mermaid block) and crystallize policy applies, verify **`.viepilot/architecture/<type>.mermaid`** exists and that **Diagram source** lines in `ARCHITECTURE.md` match; for `N/A`, sidecar file should be absent (no empty stubs)
 
 **Tier 3 — Stack Best Practices + Code Quality (mọi project, theo stack detect được):**
 - Detect stacks liên quan từ context/project manifests

package/skills/vp-crystallize/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-crystallize
 description: "Chuyển đổi brainstorm thành executable artifacts"
-version: 0.5.1
+version: 0.5.2
 ---
 
 <cursor_skill_adapter>
@@ -38,6 +38,7 @@ Chuyển đổi brainstorm sessions thành structured artifacts để AI có th
 ├── AI-GUIDE.md          # Navigation cho AI
 ├── PROJECT-META.md      # Metadata dự án
 ├── ARCHITECTURE.md      # System design
+├── architecture/        # ENH-022: *.mermaid sidecars (mirror fenced diagrams)
 ├── PROJECT-CONTEXT.md   # Domain knowledge + `<product_vision>` (phased scope)
 ├── SYSTEM-RULES.md      # Coding rules & standards
 ├── ROADMAP.md           # MVP phases & tasks + **Post-MVP / Product horizon** block (mandatory)
@@ -143,6 +144,7 @@ Ask user for (confirm proposals từ profile nếu có):
   - `required` => include concrete Mermaid block
   - `optional` => allow lightweight/merged representation
   - `N/A` => keep section heading + one-line rationale
+- **ENH-022:** For each diagram type with real Mermaid, write **`.viepilot/architecture/<type>.mermaid`** (raw source) and keep it **identical** to the body inside the fenced ` ```mermaid ` block in `ARCHITECTURE.md`; omit files for `N/A` or no diagram — see `workflows/crystallize.md` Step 4.
 
 ### Step 5: Generate PROJECT-CONTEXT.md
 - **FEAT-009:** Block `## ViePilot active profile (FEAT-009)` khi có binding
@@ -206,5 +208,6 @@ Ask user for (confirm proposals từ profile nếu có):
 - [ ] Project files created
 - [ ] Git committed
 - [ ] ARCHITECTURE diagram matrix is present and consistent (`required|optional|N/A`)
+- [ ] **ENH-022:** Mỗi diagram Mermaid được sinh có file `.viepilot/architecture/<canonical-name>.mermaid` đồng bộ nội dung với `ARCHITECTURE.md` (không tạo file thừa cho N/A)
 - [ ] **FEAT-009:** Nếu có profile bound — ARCHITECTURE + PROJECT-CONTEXT ghi nguồn profile; nếu không — ghi rõ none / not configured
 </success_criteria>

package/templates/project/ARCHITECTURE.md

@@ -4,6 +4,8 @@
 
 {{SYSTEM_OVERVIEW_DESCRIPTION}}
 
+**Diagram source (when Mermaid):** `.viepilot/architecture/system-overview.mermaid`
+
 ```
 {{SYSTEM_DIAGRAM}}
 ```
@@ -28,6 +30,12 @@
 | deployment | {{DIAGRAM_STATUS_DEPLOYMENT}} | {{DIAGRAM_REASON_DEPLOYMENT}} |
 | user-use-case | {{DIAGRAM_STATUS_USER_USE_CASE}} | {{DIAGRAM_REASON_USER_USE_CASE}} |
 
+## Diagram source files (ENH-022)
+
+When crystallize emits a real Mermaid diagram for a type, it also writes **`.viepilot/architecture/<type>.mermaid`** (raw Mermaid, no markdown fences). Canonical names: `system-overview.mermaid`, `data-flow.mermaid`, `event-flows.mermaid`, `module-dependencies.mermaid`, `deployment.mermaid`, `user-use-case.mermaid`. Types marked **N/A** or without a diagram must **not** get a sidecar file.
+
+Under each diagram section below, when applicable, include **Diagram source** pointing at the matching path. The fenced ` ```mermaid ` body in this file must **mirror** the `.mermaid` file line-for-line.
+
 ## Services
 
 {{#SERVICES}}
@@ -42,12 +50,16 @@
 
 ## Data Flow
 
+**Diagram source (when generated):** `.viepilot/architecture/data-flow.mermaid`
+
 ```
 {{DATA_FLOW_DIAGRAM}}
 ```
 
 ### Event Flows
 
+- **Diagram source (when generated):** `.viepilot/architecture/event-flows.mermaid`
+
 - **Status**: {{DIAGRAM_STATUS_EVENT_FLOWS}}
 - **Not applicable rationale**: {{DIAGRAM_NA_EVENT_FLOWS}}
 
@@ -58,6 +70,8 @@ flowchart LR
 
 ### Module Dependencies
 
+- **Diagram source (when generated):** `.viepilot/architecture/module-dependencies.mermaid`
+
 - **Status**: {{DIAGRAM_STATUS_MODULE_DEPENDENCIES}}
 - **Not applicable rationale**: {{DIAGRAM_NA_MODULE_DEPENDENCIES}}
 
@@ -68,6 +82,8 @@ flowchart LR
 
 ### User Use-Case Flows
 
+- **Diagram source (when generated):** `.viepilot/architecture/user-use-case.mermaid`
+
 - **Status**: {{DIAGRAM_STATUS_USER_USE_CASE}}
 - **Not applicable rationale**: {{DIAGRAM_NA_USER_USE_CASE}}
 
@@ -108,6 +124,8 @@ flowchart TD
 
 ## Deployment Architecture
 
+**Diagram source (when generated):** `.viepilot/architecture/deployment.mermaid`
+
 ```
 {{DEPLOYMENT_DIAGRAM}}
 ```

package/workflows/crystallize.md

@@ -287,6 +287,27 @@ Generation rules:
 - `optional`: may be simplified or merged with a nearby section, but keep section heading discoverable
 - `N/A`: keep heading and add one-line rationale (`Not applicable: ...`) so `vp-audit` and `vp-auto` can interpret intent
 - Never default to “all six detailed diagrams”; diagram depth must scale with project complexity from brainstorm.
+
+### Architecture diagram source files on disk (ENH-022)
+
+When a diagram type is **`required`** or **`optional`** and you emit a **non-empty Mermaid diagram** for it, also persist the **same** diagram body (Mermaid source only — **no** markdown fences) under **`.viepilot/architecture/`** using the canonical filenames below. When status is **`N/A`** or the section has **no** real diagram (placeholder-only / rationale-only), **do not** create the matching `.mermaid` file (and remove a stale file if regenerating a project).
+
+| Diagram type (matrix key) | File (under `.viepilot/architecture/`) |
+|---------------------------|----------------------------------------|
+| `system-overview` | `system-overview.mermaid` |
+| `data-flow` | `data-flow.mermaid` |
+| `event-flows` | `event-flows.mermaid` |
+| `module-dependencies` | `module-dependencies.mermaid` |
+| `deployment` | `deployment.mermaid` |
+| `user-use-case` | `user-use-case.mermaid` |
+
+**Single source of truth (mirror policy):** the line-for-line Mermaid **inside** the ` ```mermaid ` fence in `.viepilot/ARCHITECTURE.md` must match the contents of the paired `.viepilot/architecture/<name>.mermaid` file. If you update one, update the other in the same crystallize pass.
+
+**System overview exception:** if the overview uses a non-Mermaid diagram (e.g. ASCII in a plain ` ``` ` block) and matrix marks `system-overview` as `required`, prefer converting to Mermaid for consistency; if you keep ASCII only, **omit** `system-overview.mermaid` and state that choice in the matrix reason column.
+
+**Discoverability:** in `.viepilot/ARCHITECTURE.md`, under each diagram section that has a sidecar file, add a line with bold label **Diagram source** and an inline-code path `.viepilot/architecture/<filename>.mermaid`.
+
+Create `.viepilot/architecture/` only when at least one `.mermaid` file will be written (empty directory otherwise is unnecessary).
 </step>
 
 <step name="generate_context">
@@ -480,6 +501,7 @@ Display summary:
  │   ├── AI-GUIDE.md
  │   ├── PROJECT-META.md
  │   ├── ARCHITECTURE.md
+ │   ├── architecture/   (*.mermaid sidecars when diagrams generated — ENH-022)
  │   ├── PROJECT-CONTEXT.md
  │   ├── SYSTEM-RULES.md
  │   ├── ROADMAP.md ({phase_count} phases)