@jakkrichm/create-nexus-devflow 2.16.4 → 2.17.0

package/template/.claude/skills/feature/reference/build-history.md

@@ -0,0 +1,79 @@
+# Build history identity
+
+Read metadata from the archived original spec, not appended findings or review.
+Read the feature ID from its `**From build-plan:**` or supported legacy
+feature field, not its title or filename. Normalize the numeric part by removing
+leading zeros and the optional letter to lowercase (`012A` becomes `12a`). Match
+that complete ID, never a substring. Use the archived spec's positive integer
+`**Build attempt:**`; duplicate or malformed fields stop selection. A legacy
+first-build archive without it counts as attempt 1 only when its spec identity
+and unsuffixed `NN-name.md` path agree unambiguously. Derive the expected name
+from its own spec, not today's renamed plan title. Text such as `Build 2` in a
+title proves no attempt.
+For new paths, pad the numeric part to at least two digits, keep its letter, and
+use the spec title's lowercase kebab-case slug. Append `--build-N` only for N > 1.
+An archive declaring an attempt must agree with that computed path.
+The double hyphen is reserved: slug normalization collapses punctuation runs to
+one hyphen, so a first build titled `Export Build 2` uses `04-export-build-2.md`,
+while a later attempt 2 titled `Export` uses `04-export--build-2.md`.
+
+Before freezing a new spec, check its exact planned archive path in `devflow/history/features/` and branch.
+Require `lstat` to return `ENOENT` for the archive leaf; any existing entry,
+including a dangling symlink, blocks it. Present parents must be ordinary
+directories. Require a valid branch name and no existing or namespace-conflicting
+local branch ref (inspect `git for-each-ref refs/heads/`, including packed refs).
+Also require no prior use of the archive path in available Git history:
+
+```bash
+git log --all --reflog --full-history --format=%H -- <planned-archive-path>
+```
+
+Any result or inspection failure stops before spec review with the exact collision.
+Do not auto-bump the attempt or rename reviewed work to avoid it. These checks
+apply to new specs; existing completion must run its recovery routing first so
+its own archive is reconciled rather than rejected. Preserve already-reviewed
+legacy spec bytes, branch, and any proven recovery destination.
+
+A legacy rebuild can preserve a reviewed spec without this field. Its completion
+annotation must freeze the original `baseCommit`: resolve only prior builds and
+their completed reversals present at that base, derive `max(attempts) + 1`, and
+require the exact resulting archive path. For an integrated archive, its unique
+introducing commit's sole parent must equal that base. For unfinished completion,
+use Complete's phase proof. The path checks this derived attempt; it never supplies
+the number. Missing or ambiguous proof stops without rewriting the archived spec.
+Settled history numbering and rollback selection do not require the annotation's
+historical `head` or `sourceTree`; actual completion recovery still requires them.
+
+Before using prior builds or reversals, prove each selected record on the local
+default branch. Resolve the unique introducing commit with:
+
+```bash
+git log --full-history --diff-filter=A --format=%H <local-default> -- <archive-path>
+git log --full-history --format=%H <introducing-commit>..<local-default> -- <archive-path>
+```
+
+The first result must contain exactly one commit which actually adds the path;
+the second must be empty. Confirm the current blob and mode equal that addition
+(use Git's normal EOL normalization for a working-file comparison). Inspect the
+record at that commit, not an uncommitted replacement. Reject orphan, overwritten,
+deleted/re-added, renamed, multiply-added, or conflicting records. Never choose
+the newest commit, file count, or timestamp to resolve ambiguity.
+
+A build is reversed only by a completed `**Type:** Rollback` record in `devflow/history/rollbacks/` with its exact
+`**Target archive:**` and full `**Target commit:**`, matching feature ID, verified
+or complete status and finished steps. Its `Target parent` must match the target's
+sole parent. Prove that rollback record's unique unchanged addition
+by the same procedure, reachable on the local default after the target build.
+Require a non-merge rollback commit containing that record and its completed
+plan bookkeeping. Uncommitted, malformed, changed, or merely rollback-looking
+files are not completed reversals. Conflicting or duplicate reversals stop.
+
+Include exact rollback references retained on the selected plan line; missing
+referenced records are a blocker, not an empty history. For a new unchecked feature,
+use 1 when there are no prior records; otherwise
+require every prior build to have one proven completed reversal and allocate
+`max(attempts) + 1`. Duplicate attempts or inconsistent/missing history stop with
+the exact paths and missing proof. Search only this feature's records and their
+exact reversal references. Ignored local-only history without introducing-commit
+proof cannot establish a rebuild or rollback target; stop without force-adding or
+migrating it. Ordinary first builds do not require prior history.

package/template/.claude/skills/idea/SKILL.md

@@ -26,32 +26,32 @@ When invoked:
 3. Allocate the next sequential ID (e.g. `IDEA-001`, `IDEA-002`).
 
 ### 2. AI Feasibility & Value Analysis
-Evaluate the user's raw idea and generate an enriched summary in **Thai (`th`)**:
-- **ไอเดียตั้งต้น (Raw Idea)**: ข้อความที่ผู้ใช้ระบุ
-- **AI Feasibility & Tech**: ประเมินความเป็นไปได้ (ง่าย / ปานกลาง / ซับซ้อน) พร้อมแนะนำ Library, API, หรือแนวทางเทคนิคเบื้องต้น
-- **Value & Potential**: คุณค่า ประโยชน์ และความน่าสนใจของฟีเจอร์นี้
-- **Quick Seed (สรุปประเด็นกันลืม)**: 2-3 ประเด็นทางเทคนิคหรือแนวทางการต่อยอด เพื่อให้กลับมาอ่านทีหลังแล้วจำบริบทได้ทันที
+Evaluate the user's raw idea and generate an enriched entry in Thai (`th` per user communication rules):
+- **Raw Idea**: The user's input description
+- **AI Feasibility & Tech**: Feasibility rating (Easy / Medium / Complex) along with recommended libraries, APIs, or architectural approaches
+- **Value & Potential**: Business value, user benefits, and strategic impact
+- **Quick Seed**: 2-3 key technical nuances or seed points to preserve context for later pickup
 
 ### 3. Append to `devflow/ideas.md`
 Insert the new idea block directly under `## 📌 Pending Ideas` in `devflow/ideas.md`:
 
 ```markdown
-### [IDEA-001] {หัวข้อไอเดียสั้นๆ}
+### [IDEA-001] {Brief idea title}
 - **บันทึกเมื่อ**: {YYYY-MM-DD}
-- **ไอเดียตั้งต้น**: {ข้อความที่ผู้ใช้ป้อน}
-- **AI Feasibility & Tech**: {บทวิเคราะห์ความเป็นไปได้และเครื่องมือ}
-- **Value & Potential**: {บทวิเคราะห์คุณค่าและความน่าสนใจ}
+- **ไอเดียตั้งต้น**: {User's raw idea text}
+- **AI Feasibility & Tech**: {Feasibility and tooling analysis}
+- **Value & Potential**: {Value and impact analysis}
 - **Quick Seed (กันลืม)**:
-  1. {ประเด็นสำคัญที่ 1}
-  2. {ประเด็นสำคัญที่ 2}
-- **สถานะ**: `Pending` (หยิบไปทำได้ด้วย `/feature IDEA-001` หรือ `/discovery IDEA-001`)
+  1. {Key point 1}
+  2. {Key point 2}
+- **สถานะ**: `Pending` (Ready for pickup via `/feature IDEA-001` or `/discovery IDEA-001`)
 ```
 
-*(หากมีข้อความ `*(ยังไม่มีไอเดียค้างอยู่...)*` ให้ลบออกเมื่อมีไอเดียแรก)*
+*(If placeholder `*(ยังไม่มีไอเดียค้างอยู่...)*` exists, remove it upon recording the first idea)*
 
 ### 4. Output Summary
 Report to the user:
 - Allocated Idea ID: `[IDEA-xxx]`
 - Summary of Feasibility & Value analysis
 - Seed points saved
-- Instructions for promotion: "เมื่อพร้อมลงมือทำ สามารถพิมพ์ `/feature IDEA-xxx` หรือ `/discovery IDEA-xxx` ได้ทันที"
+- Instructions for promotion: "Ready to implement? Run `/feature IDEA-xxx` or `/discovery IDEA-xxx` anytime."

package/template/.claude/skills/rollback/SKILL.md

@@ -53,16 +53,23 @@ skill.
 
 ## Step 1 - resolve the exact feature
 
-Match the requested number or name against both the checked build-plan items and
-`devflow/history/features/*.md`. Exclude the directory README.
-
-Use the archive path to locate the commit that added it:
-
-    git log --diff-filter=A --format="%H %s" HEAD -- <archive-path>
-
-Use the newest matching commit reachable from the current branch. Confirm the
-archive was added by that commit and its subject and diff are consistent with the
-requested feature. If the target is a merge commit, stop before Step 2 and before
+Resolve the requested number or name to one checked build-plan ID; for an archive
+path, read its exact spec identity first and match that checked item. Then gather
+all exact-ID feature archive candidates using `../feature/reference/build-history.md`.
+Normalize the stable ID, retaining its letter, and read attempts from verified
+spec metadata/history proof, never arbitrary title or filename suffixes.
+
+For each candidate, require its unique introducing commit on the local default
+and prove the archive blob and mode have not changed since that addition. Exclude
+builds with a proven completed reachable rollback naming that exact archive and
+introducing commit. The checked item must have exactly one unreversed build.
+An explicit archive request stays bound to that exact path: reject it if already
+reversed, rather than silently choosing another build. Ambiguous, orphan,
+overwritten, multiply-added, or missing records stop with their exact paths and
+missing proof. Do not select by newest commit, filename order, or rollback date.
+
+Confirm the selected commit's diff is consistent with the requested feature.
+If the target is a merge commit, stop before Step 2 and before
 writing or changing `devflow/context/{xxx-slug}/spec.md`. Do not record a
 target parent or choose a mainline. Publish `blocked` to
 `devflow/.state/run.json`, explain that DevFlow cannot safely infer which
@@ -129,6 +136,12 @@ Allocate sequential ID (`xxx-slug`) and create `devflow/context/{xxx-slug}/`. Wr
 - compatibility work that is allowed, if any
 - exact verification commands and observable removal criteria
 
+Before freezing a new rollback spec, apply the archive-path and branch-availability
+checks in `../feature/reference/build-history.md` to its planned branch and
+`YYYY-MM-DD-<exact-target-archive-stem>.md` destination. Retain `--build-N` in the
+target stem when present. A collision stops for an explicit decision; never
+renumber the target or silently rename reviewed work. Existing completion recovery runs first.
+
 The first build step must apply the target commit's product diff in reverse using
 the guarded Type: Rollback behavior in `/implement`. Later steps may repair only
 the specific downstream compatibility issues named in the spec. Do not use a

package/template/AGENTS.md

@@ -5,20 +5,21 @@ Instructions for AI coding agents working in this project. This is the cross-too
 ## What this is
 
 This project uses **Nexus-DevFlow**, an agentic workflow layer supporting **The 3-Pillars Workspace Architecture & Pure Task-Isolated Living Spec Model**:
-1. **🔮 Future (Backlog)**: `devflow/ideas.md`, `devflow/project-plan.md`, `devflow/build-plan.md` — Centralized Idea Inbox & Master Build Plan.
-2. **⚡ Present (Active Context)**: `devflow/context/` — Global Shared Source of Truth (`project-overview.md`, `coding-standards.md`, `ai-interaction.md`, `glossary.md`) & Active Task Workspaces (`devflow/context/{xxx-slug}/`).
-3. **📦 Past (History Archive)**: `devflow/history/` — Categorized delivery archives (`features/`, `fixes/`, `rollbacks/`, and `HISTORY.md`).
+1. **🔮 Future (Backlog)**: `devflow/ideas.md`, `devflow/project-plan.md`, `devflow/build-plan.md` (or Decade-Numbered `devflow/10-ideation/` & `devflow/30-planning/`).
+2. **⚡ Present (Active Context)**: `devflow/context/` (or Decade-Numbered `devflow/00-context/`) — Global Shared Source of Truth (`project-overview.md`, `coding-standards.md`, `ai-interaction.md`, `glossary.md`) & Active Task Workspaces (`devflow/context/{xxx-slug}/` or `devflow/40-tasks/{xxx-slug}/`).
+3. **📦 Past (History Archive)**: `devflow/history/` (or Decade-Numbered `devflow/50-history/`) — Categorized delivery archives (`features/`, `fixes/`, `rollbacks/`, and `HISTORY.md`).
 
-To start a new project, scaffold the application first in an empty folder, then run `npx nexus-devflow` (or `npm create @jakkrichm/nexus-devflow`) to overlay DevFlow onto your codebase.
+To start a new project, scaffold the application first in an empty folder, then run `npx nexus-devflow` (or `npm create @jakkrichm/nexus-devflow`) to overlay DevFlow onto your codebase. To migrate an existing workspace to the Decade-Numbered Stages structure (`00-context`, `10-ideation`, `20-discovery`, `30-planning`, `40-tasks`, `50-history`, `60-docs`), run `npx nexus-devflow migrate-structure`.
 
 ## Read these for full context
 
 - `devflow/config.json` - deterministic project workflow settings
-- `devflow/context/project-overview.md` - the project's source of truth
-- `devflow/context/coding-standards.md` - engineering conventions & rules to follow
-- `devflow/context/ai-interaction.md` - how to interact with the user on this project
-- `devflow/context/glossary.md` - domain terms & architecture definitions
-- `devflow/context/{xxx-slug}/` - active task living spec, stage, findings ledger, and independent review receipt
+- `devflow/00-context/` (or `devflow/context/`) `project-overview.md` - the project's source of truth
+- `devflow/00-context/` (or `devflow/context/`) `coding-standards.md` - engineering conventions & rules to follow
+- `devflow/00-context/` (or `devflow/context/`) `ai-interaction.md` - how to interact with the user on this project
+- `devflow/00-context/` (or `devflow/context/`) `glossary.md` - domain terms & architecture definitions
+- `devflow/40-tasks/{xxx-slug}/` (or `devflow/context/{xxx-slug}/`) - active task living spec, stage, findings ledger, and independent review receipt
+
 
 ## Project configuration
 
@@ -42,7 +43,7 @@ Unused adapter families can be removed. Codex, Antigravity, GitHub Copilot, and
 
 ### Universal Invocation & Agent Directives:
 
-1. **Canonical Command Names & AI Provider Invocation**: Each workflow stage and companion tool has exactly **one Canonical Name** (e.g. `feature`, `fix`, `implement`, `check`, `complete`, `continuous`, `analyze`, `discovery`, `idea`, `grill`, `brainstorm`, `bughunter`, `devflow`, `doctor`, `overview`, `debug`, `onboard`, `adopt`, `try`, `rollback`, `ci`, `test`, `setup-tests`, `browser-tests`, `autopilot`, `prototype`, `report-html`, `brief`, `audit`, `release`, `convert-any-to-md`, `publish-devflow`, `matt-pocock`). The way you invoke commands depends on your AI Provider / Tool:
+1. **Canonical Command Names & AI Provider Invocation**: Each workflow stage and companion tool has exactly **one Canonical Name** (e.g. `feature`, `fix`, `implement`, `check`, `complete`, `continuous`, `analyze`, `discovery`, `idea`, `grill`, `brainstorm`, `bughunter`, `devflow`, `doctor`, `overview`, `debug`, `onboard`, `adopt`, `try`, `rollback`, `ci`, `test`, `setup-tests`, `browser-tests`, `autopilot`, `prototype`, `report-html`, `brief`, `audit`, `release`, `convert-any-to-md`, `publish-devflow`, `vendor`). The way you invoke commands depends on your AI Provider / Tool:
    - **Canonical Name (Plain text)**: Directly invoke or prompt the command by its standard name (e.g., `feature`, `implement`, `continuous`, `devflow`, `discovery`, `analyze`).
    - **Slash Prefix (`/`)**: For tools supporting slash commands (Claude Code, Google Antigravity, Gemini CLI), e.g., `/feature`, `/fix`, `/implement`, `/continuous`, `/devflow`, `/discovery`, `/analyze`.
    - **Dollar Prefix (`$`)**: For OpenAI Codex CLI or skill-invocation tools, e.g., `$feature`, `$fix`, `$continuous`, `$devflow`, `$discovery`, `$analyze`.

package/template/devflow/{context → 00-context}/ai-interaction.md

@@ -148,7 +148,7 @@ Progress lives in persistent files, not in transient chat history:
 
 - **Branch Naming**: `feature/{xxx-slug}` or `fix/{xxx-slug}`.
 - **Commit Messages**: Conventional imperative format (e.g. `feat(uninstall): add clean eject CLI command`, `fix(parser): handle undefined metadata field`).
-- **No AI Attribution in Commits**: Never include "Generated with AI" or agent metadata in Git commit logs.
+- **No AI Attribution in Commits**: Never include "Generated with AI", AI `Co-Authored-By` trailers, or agent metadata in Git commit logs or PR descriptions; preserve genuine human attribution. Claude Code supports `"attribution": { "commit": "", "pr": "" }` in `.claude/settings.json` to suppress default signatures.
 - **Explicit Approval for Push & Deploy**: Merge approval is strictly separate from consent to `git push` to remote repositories or deploy to production.
 
 ---

package/template/devflow/{build-plan.md → 30-planning/build-plan.md}

@@ -276,3 +276,27 @@
 - [x] **35. Superpowers Debugging Heuristics & TDD Reference Guides (`DISC-20260909-003`, `085-superpowers-debugging-heuristics-integration`)** `[Size: S]`
   - *Dependencies*: Feature 31 (`081`), Feature 32 (`082`)
   - *Scope*: เพิ่ม JIT reference guides สำหรับ root-cause tracing, defense-in-depth, condition-based waiting, TDD anti-patterns และ two-stage review พร้อม 3-Strike Rule และ Iron Law; ซิงก์ `.agents/` กับ `.claude/` และตรวจ file contracts
+
+---
+
+## Phase 36: Upstream AI Blueprint v1.6.1 Synchronization
+
+- [x] **36. Sync Upstream v1.6.1 (Installer Symlink Rejection, Completion Recovery Engine, Rebuild History Preservation, Local-Only Spec Review & Status Evidence Alignment) (`DISC-20260911-001`, `086-sync-upstream-ai-blueprint-v161`)** `[Size: M]`
+  - *Dependencies*: Feature 28 (`073`), DISC-20260911-001
+  - *Scope*: นำเข้า 5 เสาหลักความปลอดภัยและความแม่นยำจาก AI Blueprint v1.6.1: (1) ปฏิเสธ Symlink paths และตรวจ type compatibility ในตัวติดตั้ง `create-nexus-devflow`, (2) สร้างสัญญา `completion-recovery.md` พร้อม JSON comment annotation `<!-- devflow:completion ... -->` กู้คืนการส่งมอบงานที่สะดุด, (3) สร้างสัญญา `build-history.md` รองรับการตั้งชื่อ `--build-N` เมื่อ Rebuild ฟีเจอร์ที่เคยถูก Rollback, (4) ขยาย `lib/review.ts` ให้รองรับ `specSnapshot` สำหรับ Local-only spec review, (5) บูรณาการ `classifyWorkEvidence` ใน `project-status-engine.ts` และ `dashboard.ts` ป้องกัน False Ready State เมื่อ verification failed หรือพบ malformed records, (6) ซิงก์สคิลและเอกสารทั้ง `.agents/` และ `.claude/` พร้อม automated tests ผ่าน 100%
+
+## 🔌 Phase 37: AI-Orchestrated Project-Local Vendor Skill Ingestion (`/vendor`)
+
+- [x] **37. AI-Orchestrated Project-Local Vendor Skill Ingestion (`DISC-20260911-002`, `087-ai-orchestrated-vendor-skill-ingestion`)** `[Size: M]`
+  - *Dependencies*: Feature 33 (`083`), Feature 34 (`084`), DISC-20260911-002
+  - *Scope*: พัฒนาคำสั่ง `/vendor` (พร้อม aliases: `skill-add`, `equip`, `ingest`) สำหรับนำเข้า Git repository ลงในระดับโปรเจกต์ `devflow/.vendor/<slug>/`, ให้ AI Agent สำรวจโค้ดและสังเคราะห์ Custom Wrapper Skill ใน `.agents/skills/<slug>/SKILL.md` และ `.claude/skills/<slug>/SKILL.md`, พัฒนากลไก Update Protection ใน `update.ts` เพื่อป้องกันไม่ให้คำสั่งอัปเดต DevFlow ลบ custom skills เหล่านี้, บันทึก metadata ลง `.nexus/nexus-devflow.json`, ปรับปรุง CLI `nexus-devflow skill update all` ให้รองรับการ pull upstream ใน `.vendor/` โดยคงรักษา custom wrapper ที่ AI เขียนไว้, พร้อมเขียน Automated Unit Tests ครอบคลุม 100%
+
+---
+
+## 📂 Phase 38: Decade-Numbered Folder Architecture & Multi-Version Migration Engine
+
+- [x] **38. Decade-Numbered Folder Architecture, Legacy Path Resolver & Structure Migration Engine (`REQ-20260911-001`, `088-decade-numbered-folder-architecture`)** `[Size: M]`
+  - *Dependencies*: None
+  - *Scope*: ปรับสถาปัตยกรรมโฟลเดอร์ของ DevFlow ให้จัดเรียงตาม Decade-Numbered Stages (`00-context`, `10-ideation`, `20-discovery`, `30-planning`, `40-tasks`, `50-history`, `60-docs`), สร้าง Dynamic Path Resolver Engine รองรับ Client เวอร์ชันเก่าแบบ Zero-Breaking Change, พัฒนา CLI Subcommand `nexus-devflow migrate-structure` ทำการย้ายโฟลเดอร์และอัปเดต Manifest/Config อัตโนมัติ, ลบโฟลเดอร์ Legacy `devflow/runs/`, อัปเดตคู่มือ `AGENTS.md`, `CLAUDE.md`, `README.md`, Playbooks และเขียน Automated Tests ครอบคลุม
+
+

package/template/devflow/40-tasks/README.md

@@ -0,0 +1,11 @@
+# ⚡ 40-tasks: Active Living Spec Workspaces
+
+This directory contains active, isolated task workspaces (`{xxx-slug}/`) during development.
+
+Each active task folder contains:
+- `spec.md` - Task-isolated living specification and implementation checklist
+- `stage.md` - Lifecycle stage tracker (`defined`, `in-progress`, `checked`, `verified`)
+- `findings.md` - Dedicated findings ledger for audit and verification proof
+- `review.md` - Optional independent review request and receipt
+
+When a task is completed via `/complete`, its spec is archived to `devflow/50-history/features/` (or `fixes/`, `rollbacks/`) and the active folder in `40-tasks/` is cleanly removed.

package/template/devflow/60-docs/migration-guide-decade-numbered.md

@@ -0,0 +1,93 @@
+# คู่มือการย้ายโครงสร้างโฟลเดอร์สู่ Decade-Numbered Stages (Migration Guide)
+
+> **DevFlow Version**: 2.16.5+  
+> **Topic**: การจัดระเบียบโฟลเดอร์ `devflow/` ตามลำดับขั้นตอนด้วย Decade-Numbered Stages และการอัปเกรดจากโครงสร้างเดิม
+
+---
+
+## 🌟 1. สถาปัตยกรรมโฟลเดอร์ Decade-Numbered Stages
+
+เพื่อแก้ปัญหาโฟลเดอร์ใน `devflow/` กระจัดกระจายและไม่มีตัวเลขจัดเรียงสายตาใน IDE ทาง DevFlow ได้แนะนำโครงสร้าง **Decade-Numbered Stages Structure** (`00-`, `10-`, `20-`, ...) ที่ช่วยให้ทั้งผู้ใช้งานและ AI Agent ไล่ลำดับขั้นตอนการพัฒนาได้อย่างเป็นธรรมชาติ:
+
+```text
+devflow/
+├── config.json                     # Root configuration
+├── .state/                         # Runtime state (run.json - Git ignored)
+├── .vendor/                        # External vendor skills (bughunter, ponytail, ฯลฯ)
+│
+├── 00-context/                     # [Foundation & Source of Truth]
+│   ├── project-overview.md         # Living overview (สถาปัตยกรรม & tech stack ล่าสุด)
+│   ├── coding-standards.md         # กฎระเบียบและมาตรฐานการเขียนโค้ด
+│   ├── ai-interaction.md           # ข้อกำหนดการทำงานร่วมกับ AI Agent
+│   └── glossary.md                 # พจนานุกรมศัพท์เฉพาะของระบบ
+│
+├── 10-ideation/                    # [Input & Reference Ingestion]
+│   ├── ideas.md                    # บันทึกไอเดียใหม่ (Idea Inbox)
+│   ├── inbox/                      # ไฟล์ดิบจากภายนอก (PDF, Excel, Word, ภาพ)
+│   └── reference/                  # เอกสารที่แปลงเป็น Markdown สะอาดพร้อมใช้งาน
+│
+├── 20-discovery/                   # [Analysis, Exploration & Architecture]
+│   ├── analysis/                   # ผลการวิเคราะห์ System Analyst (/analyze)
+│   ├── discoveries/                # Pre-flight Spikes & Research (/discovery)
+│   ├── decisions/                  # บันทึกการตัดสินใจ ADRs (/grill)
+│   ├── research/                   # เอกสารวิจัยเชิงลึกและ Benchmark
+│   ├── 21-prototype/               # (Optional: Static UI mockups / prototype)
+│   └── 22-diagrams/                # (Optional: System & Architecture Diagrams)
+│
+├── 30-planning/                    # [Roadmap & Master Plans]
+│   ├── project-plan.md             # Master Roadmap & Milestones
+│   └── build-plan.md               # Master Delivery Checklist
+│
+├── 40-tasks/                       # [Active Living Spec Workspaces]
+│   └── {xxx-slug}/                 # Active task workspace (สร้างตอนทำฟีเจอร์/แก้บั๊ก)
+│       ├── spec.md                 # Task-Isolated Living Spec
+│       ├── stage.md                # ตัวชี้สถานะ Stage
+│       ├── findings.md             # บันทึกบั๊ก/Audit ประจำงาน
+│       └── tickets/                # Tracer-bullet tickets ย่อย
+│
+├── 50-history/                     # [Shipped & Delivered Archives]
+│   ├── HISTORY.md                  # Release Ledger สรุปภาพรวมประวัติ
+│   ├── features/                   # ฟีเจอร์ที่ส่งมอบแล้ว
+│   ├── fixes/                      # บั๊กที่แก้แล้ว
+│   └── rollbacks/                  # ฟีเจอร์ที่ถูก rollback
+│
+└── 60-docs/                        # [Documentation & System Playbooks]
+    └── playbooks/                  # Interactive HTML Playbooks (5W1H)
+```
+
+---
+
+## ⚡ 2. จุดเด่นของการใช้เลขทศวรรษ (Decade Convention: `00-`, `10-`, `20-`)
+
+1. **ลำดับสายตาใน Editor สวยงาม**: เรียงตามลำดับความก้าวหน้าของโครงการ
+2. **ขยาย Sub-stages ในอนาคตได้ง่าย (Future-Proof)**: สามารถสร้างโฟลเดอร์แทรก เช่น `21-prototype`, `22-diagrams` ได้โดยไม่ต้องแก้เลขนำหน้าของโฟลเดอร์อื่น
+3. **ตัดโฟลเดอร์ Legacy ออก 100%**: ลบโฟลเดอร์ `devflow/runs/` ที่ไม่ได้ใช้งานตั้งแต่ v1.x ออกอย่างปลอดภัย
+
+---
+
+## 🚀 3. วิธีการ Migrate อัตโนมัติ
+
+### 1) รันอัตโนมัติผ่านคำสั่ง `update` (แนะนำที่สุด):
+เมื่อโปรเจกต์ Client สั่งอัปเดตเวอร์ชัน DevFlow ด้วยคำสั่ง:
+```bash
+npx nexus-devflow update
+```
+ระบบจะตรวจจับโครงสร้างโฟลเดอร์อัตโนมัติ:
+* **หากยังเป็นโครงสร้างเดิม (Legacy)**: ระบบจะรันกระบวนการ `migrate-structure` ให้อัตโนมัติทันที พร้อมย้ายไฟล์เข้า `00-`, `10-`, `20-`, `30-`, `40-`, `50-`, `60-` และลบ `devflow/runs/`
+* **หากเป็นโครงสร้าง Decade-Numbered อยู่แล้ว**: ระบบจะไม่ทำอะไรกับโฟลเดอร์ (No-op) และดำเนินการอัปเดตโค้ดต่อไปอย่างปลอดภัย
+
+### 2) สั่ง Migrate ด้วยตัวเองโดยตรง:
+หากต้องการย้ายโครงสร้างทันทีโดยไม่อัปเดตส่วนอื่น สามารถสั่งได้ผ่านคำสั่ง:
+```bash
+npx nexus-devflow migrate-structure
+```
+
+
+---
+
+## 🛡️ 4. การรองรับ Client เวอร์ชันเก่า (Zero-Breaking Compatibility)
+
+ระบบ DevFlow มีกลไก **Dynamic Workspace Path Resolver** (`resolveWorkspacePaths`) ที่จะ:
+1. ตรวจสอบว่าโปรเจกต์ใช้โครงสร้าง Decade-Numbered หรือไม่ (มี `devflow/00-context` หรือไม่)
+2. หากไม่พบ จะ **Fallback กลับไปหา Path เดิม (`devflow/context/`, `devflow/history/`) อัตโนมัติ 100%**
+3. โปรเจกต์เก่าที่ยังไม่ได้ Migrate จึงยังคงรันคำสั่งสถานะ, ตรวจสอบคุณภาพ, และบิวด์ได้ตามปกติโดยไม่มีข้อผิดพลาด