@jakkrichm/create-nexus-devflow 2.5.0 → 2.6.1

package/template/devflow/context/coding-standards.md

@@ -14,16 +14,40 @@
 
 ---
 
-## 2. CLI Architecture & Engineering Principles
-
-- **Separation of Concerns (Deep Modules & Information Hiding)**:
+## 2. CLI Architecture & Deep Modules Philosophy
+
+- **Deep Modules Principles (John Ousterhout Philosophy)**:
+  - **Module**: Anything with an interface and an implementation (function, class, package, or subsystem).
+  - **Interface**: Everything a caller must know to use the module correctly (types, invariants, ordering, error modes, configuration).
+  - **Implementation**: The hidden body of code inside the module.
+  - **Depth (High Leverage)**: A module is **Deep** when a large amount of complex behavior sits behind a small, simple interface. A module is **Shallow** (to be avoided) when its interface is nearly as complex as its implementation.
+  - **Seam**: The clean architectural location where an interface lives.
+  - **Adapter**: A concrete implementer satisfying the interface at a seam.
+  - **The Deletion Test**: Imagine deleting the module. If complexity concentrates across N callers, it was earning its keep (Deep). If complexity simply vanishes or moves, it was a pass-through (Shallow).
+  - **Designing for Testability**:
+    - *Accept dependencies, don't instantiate them inside.*
+    - *Return results, minimize unobservable side effects.*
+    - *Small surface area: fewer methods and simple parameter objects.*
+- **Separation of Concerns (Information Hiding)**:
   - Keep CLI entry points (`bin/create-nexus-devflow.ts`) thin: handle argument parsing, option normalization, and terminal formatting.
   - Encapsulate all core business logic, filesystem operations, and parsing inside modular libraries (`lib/current-work.ts`, `lib/findings.ts`, `lib/git.ts`, `lib/uninstall.ts`, `lib/update.ts`).
-  - **Deep Modules**: Strive for simple, narrow interfaces that hide extensive implementation complexity internally.
 - **Refactoring & Code Simplification (Simplify Discipline)**:
   - **Early Returns**: Guard conditions should exit early to eliminate deep nesting.
   - **Single Responsibility (SRP)**: Functions should do one cohesive thing and stay under 50 lines whenever possible.
   - **Pure Functions**: Favor deterministic functions without side effects for data transformation and parsing.
+- **Baseline 12 Fowler Code Smells (Continuous Refactoring)**:
+  - **Mysterious Name**: Names that don't reveal what they do -> Rename with clear intention.
+  - **Duplicated Code**: Identical or similar logic shapes -> Extract shared helper.
+  - **Feature Envy**: Method reaching into another object's data -> Move method onto that data.
+  - **Data Clumps**: Same 3+ fields traveling together -> Bundle into a cohesive type.
+  - **Primitive Obsession**: Raw string/number representing a domain concept -> Define a branded/domain type.
+  - **Repeated Switches**: Duplicate `switch`/`if` cascades -> Use polymorphism or lookup map.
+  - **Shotgun Surgery**: One change forcing scattered edits in many files -> Unify into one deep module.
+  - **Divergent Change**: One file edited for multiple unrelated reasons -> Split responsibilities.
+  - **Speculative Generality**: Hooks/params added for hypothetical needs -> Delete and inline until needed.
+  - **Message Chains**: Long `a.b().c().d()` navigation -> Hide behind a method on the root object.
+  - **Middle Man**: Class/function that only delegates -> Remove and call target directly.
+  - **Refused Bequest**: Subclass ignoring inherited methods -> Replace inheritance with composition.
 - **Safety Flags & Idempotency**:
   - Destructive or mutating operations (e.g. `uninstall`, `update`, `install`) must support safety flags:
     - `--dry-run`: Preview actions and affected files without modifying the disk.
@@ -109,7 +133,7 @@ Testing is a core quality gate in Nexus-DevFlow, not an afterthought:
   - Never claim a task is "working", "tested", or "verified" without providing concrete empirical proof (exact command executed, terminal output, pass/fail counts, exit code).
 - **Two-Stage Review Pattern (Verification Gate)**:
   - **Stage 1: Spec Fidelity & Acceptance Gate**:
-    - Verify 100% conformance against the living spec (`current-feature.md` or `20-spec.md`).
+    - Verify 100% conformance against the Single Living Spec (`current-feature.md`).
     - Validate all Acceptance Criteria (ACs) and "Done When" observables without missing requirements or scope creep.
     - Test edge cases and boundary conditions defined in the specification.
   - **Stage 2: Code Quality, Security & Architecture Gate**:
@@ -129,7 +153,8 @@ Testing is a core quality gate in Nexus-DevFlow, not an afterthought:
   - `fixed`: Repaired in code, pending QA re-verification.
   - `closed`: Verified by QA as completely resolved without regressions.
   - `accepted`: Formally waived with recorded user justification.
-- **P0/P1 Blockers**: Any P0 or P1 finding in `open` or `fixed` status unconditionally blocks `/complete` and `70-deliver`.
+- **P0/P1 Blockers**: Any P0 or P1 finding in `open` or `fixed` status unconditionally blocks `/complete`.
+- **Allowed Waivers**: A P0 or P1 finding may only be bypassed if marked `accepted` (with explicit user justification recorded) or `invalid` (with evidence recorded by `/audit`).
 
 ---
 

package/template/devflow/context/current-stage.md

@@ -1,8 +1,11 @@
-# Current DevFlow Run Status
+# Current Stage
 
-- **Active Discovery ID**: `None`
-- **Active Running ID**: `None`
-- **Current Stage**: `Idle (Ready for new /feature, /fix, /discovery, or /10-define)`
-- **Living Spec**: `None`
-- **Last Completed Run**: `None`
-- **Last Updated**: `None`
+- Active Discovery ID: `None`
+- Active Running ID: `None`
+- Track: `idle`
+- Current Stage: `idle`
+- Active Branch: `main`
+- Living Spec: `devflow/context/current-feature.md`
+- Next Action: `Run /feature, /fix, or /discovery to start new work.`
+- Last Completed Run: `None`
+- Last Updated: `None`

package/template/devflow/history/HISTORY.md

@@ -1,6 +1,6 @@
 # Master Release History Ledger
 
-This master ledger tracks all released delivery runs, milestones, and rollbacks in chronological order. Each entry is recorded during `/complete` or `70-deliver` and links to its exact Git commit hash, release status, category, and archived delivery artifacts.
+This master ledger tracks all released delivery runs, milestones, and rollbacks in chronological order. Each entry is recorded during `/complete` and links to its exact Git commit hash, release status, category, and archived delivery artifacts.
 
 ---
 

package/template/devflow/project-plan.md

@@ -13,7 +13,7 @@
   - ทีมพัฒนาและองค์กร (Engineering Teams & Tech Leads) ที่ต้องการมาตรฐานการส่งมอบโค้ดที่ตรวจสอบได้ (Traceable), ตรวจสอบย้อนหลังได้ (Auditable) และไม่มีปัญหาโค้ดตีกัน (Zero Merge Conflict)
 - **Core Value Proposition**:
   - **The 3-Pillars Model**: จัดระเบียบบริบทเป็น 3 เสาหลักอย่างชัดเจน — *🔮 Future (Inbox `ideas.md`)* ➔ *⚡ Present (Living Context `devflow/context/`)* ➔ *📦 Past (Categorized History `devflow/history/`)*
-  - **Dual-Track Delivery Model**: เลือกความเร็วให้เหมาะกับขนาดงาน — *Fast-Track (4 ขั้นตอน)* สำหรับ 85% ของงานประจำวัน และ *Deep-Track (8 ขั้นตอน)* สำหรับ 15% ของงานสถาปัตยกรรม
+  - **Single Living Spec Delivery Model**: งานทุกขนาดใช้วงจรเดียว `/feature` (หรือ `/fix`) ➔ `/implement` ➔ `/check` ➔ `/complete` โดยเพิ่มความลึกของสเปกและหลักฐานตามความซับซ้อนของงาน
   - **Hard Quality Gates**: ระบบปฏิเสธการปล่อยงานเมื่อไม่ผ่านเกณฑ์การทดสอบ หรือมีข้อบกพร่องความปลอดภัยค้างอยู่
 
 ---
@@ -27,7 +27,7 @@
   - Local State Management & Backup Snapshots (`.nexus/`)
 - **Key Modules & Subsystems**:
   - **Distribution CLI & Package**: `packages/create-nexus-devflow` (Scaffolding, Doctor, Status, Update, Gatekeeper)
-  - **Interactive Web Dashboard**: Embedded Local Webview Dashboard (`/dashboard`) พร้อม Dual-Track Visualizer และ Real-time Snapshot
+  - **Interactive Web Dashboard**: Embedded Local Webview Dashboard (`/dashboard`) พร้อม Living Spec Visualizer และ Real-time Snapshot
   - **Gatekeeper Engine**: ระบบตรวจสอบคุณภาพโค้ดและ Finding Blockers (`nexus-devflow check-gate`)
   - **Model Context Protocol (MCP) Server**: JSON-RPC Hub สำหรับเชื่อมต่อ AI Agents แบบ Type-Safe
   - **Dynamic Context Slicer**: ระบบจัดสรรและตัดตอนบริบทแบบ Just-In-Time (JIT) เพื่อประหยัด Token

package/template/devflow/reference/running-id-contract.md

@@ -1,4 +1,4 @@
-# DevFlow 2.5.0 Running ID & 3-Pillars Workspace Contract
+# DevFlow 2.6.0 Running ID & 3-Pillars Multi-Run Context Contract
 
 ## The 3-Pillars Workspace Architecture
 
@@ -7,15 +7,23 @@ All DevFlow framework assets are organized into three clean pillars representing
 ```text
 devflow/
 ├── 🔮 ideas.md                 # [1. Future / Backlog] Centralized Idea Inbox with AI scoring
+├── 🗺️ project-plan.md          # [1. Future] Master product roadmap and system vision
+├── 📋 build-plan.md            # [1. Future] User-owned feature queue and sizing
 │
-├── ⚡ context/                  # [2. Present / Active] Living Source of Truth & Active Work
+├── ⚡ context/                  # [2. Present / Active] Living Source of Truth & Multi-Run Contexts
 │   ├── project-overview.md     # Primary source of truth for project architecture and tech stack
 │   ├── coding-standards.md     # Engineering, code quality, TDD, and testing standards
 │   ├── ai-interaction.md       # AI agent interaction rules, unified living spec flow, and Thai defaults
-│   ├── findings.md             # Open and resolved audit findings ledger (P0-P3)
 │   ├── glossary.md             # Domain glossary and architecture vocabulary
+│   ├── current-feature.md      # Active Living Spec pointer / legacy fallback
 │   ├── current-stage.md        # Active state pointer and run tracker
-│   └── current-feature.md      # Single Living Spec (Active work / stub when idle)
+│   ├── findings.md             # Shared/default audit findings ledger (P0-P3)
+│   │
+│   ├── {xxx-slug}/             # Active Run Workspace & Spec Queue (Multi-Run Active Task)
+│   │   ├── spec.md             # Living Spec + Checklist for this run
+│   │   ├── stage.md            # Runtime stage, track, and branch pointer
+│   │   └── findings.md         # Dedicated audit findings ledger for this run
+│   └── ...
 │
 ├── 📦 history/                  # [3. Past / Completed] Permanent Delivery & Release Archives
 │   ├── features/               # Completed features, architecture migrations, tooling (xxx-slug.md)
@@ -32,9 +40,9 @@ devflow/
 ## Running ID Naming Convention
 
 ### 1. Standard Running IDs
-- **Format**: `xxx-slug` (e.g. `001-setup-auth`, `053-unify-deep-and-fast-track-model`)
+- **Format**: `xxx-slug` (e.g. `001-setup-auth`, `058-multi-run-context-architecture`)
 - **Prefix Removal**: The legacy `RUN-` prefix is discontinued in favor of clean 3-digit sequential numbering.
-- **Git Branch Standard**: `feature/{xxx-slug}` or `fix/{xxx-slug}` (or specific release branches such as `2.5.0`).
+- **Git Branch Standard**: `feature/{xxx-slug}` or `fix/{xxx-slug}` (or specific release branches such as `2.6.0`).
 
 ### 2. Sub-Feature Running IDs (`xxx[a-z]-slug`)
 - **Format**: `xxx[a-z]-slug` (e.g. `038a-backend-schema-and-api`, `038b-frontend-ui-and-state`)
@@ -44,19 +52,15 @@ devflow/
 
 ---
 
-## Multi-Factor Sizing Heuristic & Splitting Engine
+## Multi-Run Spec Queue & Selective Execution Rule
 
-A feature is considered **Oversized (`L` or `XL`)** and recommended for sub-feature splitting when any of the following conditions are met:
-1. **Files Touched**: Predicted to modify or create $\ge 6$ files.
-2. **Architectural Layers**: Crosses $\ge 3$ distinct layers (e.g. Database Migrations + Backend APIs + Frontend UI + State Store).
-3. **Task Complexity**: Contains $\ge 6$ checklist tasks or involves heavy multi-service integrations.
+1. **Spec-Ahead & Non-blocking Drafting**:
+   - `/feature [id / title]` and `/fix [title]` create dedicated run folders at `devflow/context/{xxx-slug}/`.
+   - Creating a spec does **not block** drafting additional specs. Multiple specs can reside in `devflow/context/` simultaneously.
+2. **Selective Execution (`/implement [id]`)**:
+   - Spec execution can be invoked targeting a specific ID (e.g. `/implement 12`, `/implement 012`, or `/implement kanban`).
+   - The AI checks out the matching git branch `feature/{xxx-slug}`, loads only that run's `spec.md` and global context, and executes tasks with Strict TDD.
+3. **Dedicated Quality Ledger & Safe Archival (`/complete [id]`)**:
+   - Each run maintains its own `findings.md` within `devflow/context/{xxx-slug}/`.
+   - `/complete` compiles the living spec, archives it to `devflow/history/{features|fixes|rollbacks}/{xxx-slug}.md`, removes `devflow/context/{xxx-slug}/`, updates `HISTORY.md` and `build-plan.md`, and prompts for squash-merge/PR.
 
-When detected during `/feature` or `/brief`, the AI triggers the **Interactive Split Gate**, proposing a clean `4a`, `4b` sub-feature breakdown before opening the first spec.
-
----
-
-## Single Active Run Rule (One Thing at a Time)
-
-1. Only **one active run** is permitted at any given time in `current-feature.md`.
-2. Before opening a new run (`/feature` or `/fix`), the AI checks `current-stage.md` and `current-feature.md`.
-3. If an active run is in progress, the AI **blocks** starting a new task and requires closing the active run via `/complete` (or explicitly cancelling/rolling back).