@jakkrichm/create-nexus-devflow 2.13.0 → 2.15.0

package/template/devflow/docs/diagrams/nexus-devflow-lifecycle.json

@@ -0,0 +1,88 @@
+{
+  "schema_version": 1,
+  "diagram_type": "lifecycle",
+  "meta": {
+    "title": "Nexus-DevFlow Living Spec Lifecycle",
+    "output": "devflow/docs/diagrams/nexus-devflow-lifecycle.html",
+    "viewBox": [980, 680],
+    "animation": "trace",
+    "visual_preset": "signal-flow",
+    "quality_profile": "showcase",
+    "views": [
+      {
+        "id": "delivery-rail",
+        "label": "Delivery rail",
+        "focus": ["queued", "implementing", "verifying", "completing", "shipped"],
+        "note": "Follow the 4-stage progressive lifecycle from spec creation to squash-merge."
+      },
+      {
+        "id": "quality-gates",
+        "label": "Quality and review gates",
+        "focus": ["verifying", "findings_blocked", "rejected", "completing", "review_pause"],
+        "note": "Safety gates where living spec review pauses and P0/P1 findings block release."
+      },
+      {
+        "id": "reversals",
+        "label": "Post-delivery rollback",
+        "focus": ["shipped", "reversal_plan", "rolled_back"],
+        "note": "Safe reversibility of completed features using categorized history and git commits."
+      }
+    ]
+  },
+  "lanes": [
+    { "id": "main", "label": "4-Stage Living Spec Phases" },
+    { "id": "waiting", "label": "Quality & Approval Gates" },
+    { "id": "terminal", "label": "Terminal Exits & Reversals" }
+  ],
+  "states": [
+    { "id": "queued", "type": "start", "label": "1. /feature (/fix)", "sublabel": "Task-Isolated spec.md", "lane": "main", "col": 0, "step": "01", "tag": "spec" },
+    { "id": "implementing", "type": "active", "label": "2. /implement", "sublabel": "Strict TDD build", "lane": "main", "col": 1, "step": "02", "tag": "build" },
+    { "id": "verifying", "type": "decision", "label": "3. /check & /audit", "sublabel": "Multi-Lane QA Matrix", "lane": "main", "col": 2, "step": "03", "tag": "gate" },
+    { "id": "completing", "type": "waiting", "label": "4. /complete", "sublabel": "Release & Merge Gate", "lane": "main", "col": 3, "step": "04", "tag": "ready" },
+    { "id": "shipped", "type": "success", "label": "Shipped & Merged", "sublabel": "devflow/history/ & Git", "lane": "main", "col": 4, "step": "05", "tag": "merged" },
+    { "id": "findings_blocked", "type": "waiting", "label": "Findings Ledger", "sublabel": "P0/P1 Blocker gate", "lane": "waiting", "col": 0, "tag": "blocked" },
+    { "id": "review_pause", "type": "waiting", "label": "Merge Approval Gate", "sublabel": "Human decision", "lane": "waiting", "col": 1, "tag": "pause" },
+    { "id": "reversal_plan", "type": "waiting", "label": "/rollback", "sublabel": "Safe Reversal Spec", "lane": "waiting", "col": 2, "tag": "reversal" },
+    { "id": "rejected", "type": "failure", "label": "Rejected / Waived", "sublabel": "Blocker unresolved", "lane": "terminal", "col": 0, "tag": "terminal" },
+    { "id": "cancelled", "type": "failure", "label": "Cancelled", "sublabel": "Merge aborted", "lane": "terminal", "col": 1, "tag": "terminal" },
+    { "id": "rolled_back", "type": "success", "label": "Rolled Back", "sublabel": "Safely reversed", "lane": "terminal", "col": 2, "tag": "terminal" }
+  ],
+  "transitions": [
+    { "from": "verifying", "to": "findings_blocked", "variant": "security", "route": "straight", "fromSide": "bottom", "toSide": "top" },
+    { "from": "findings_blocked", "to": "rejected", "variant": "security", "route": "straight", "fromSide": "bottom", "toSide": "top" },
+    { "from": "completing", "to": "review_pause", "variant": "security", "route": "straight", "fromSide": "bottom", "toSide": "top" },
+    { "from": "review_pause", "to": "cancelled", "variant": "security", "route": "straight", "fromSide": "bottom", "toSide": "top" },
+    { "from": "shipped", "to": "reversal_plan", "variant": "dashed", "route": "straight", "fromSide": "bottom", "toSide": "top" },
+    { "from": "reversal_plan", "to": "rolled_back", "variant": "emphasis", "route": "straight", "fromSide": "bottom", "toSide": "top" }
+  ],
+  "cards": [
+    {
+      "dot": "emerald",
+      "title": "4-Stage Progressive Rail",
+      "items": [
+        "/feature drafts task-isolated spec (spec.md) and pauses for review",
+        "/implement progresses sequentially with strict Red-Green-Refactor TDD",
+        "/check evaluates dual-axis verification and records empirical proof",
+        "/complete archives to devflow/history/ and executes squash-merge"
+      ]
+    },
+    {
+      "dot": "amber",
+      "title": "Quality & Approval Gates",
+      "items": [
+        "Spec review pause ensures requirements are locked before code is written",
+        "Findings ledger (findings.md) tracks all audit issues with durable IDs",
+        "Unresolved P0/P1 blockers strictly prevent /complete merge"
+      ]
+    },
+    {
+      "dot": "rose",
+      "title": "Reversals & Exits",
+      "items": [
+        "Rejected specs exit cleanly without cluttering repository state",
+        "/rollback creates reversible spec using archived git commits",
+        "Zero regression debt through durable 3-Pillars history"
+      ]
+    }
+  ]
+}

package/template/devflow/docs/examples/living-spec/adr.example.md

@@ -0,0 +1,43 @@
+---
+id: "ADR-001-auth-architecture"
+title: "ADR: Authentication Engine Selection"
+doc_type: "decision"
+status: "accepted"
+deciders: ["Lead Architect", "Security Auditor"]
+created: "2026-08-25"
+updated: "2026-08-25"
+source_discovery: "DISC-20260825-001-user-auth"
+related_files: ["src/lib/auth.ts", "src/db/schema/auth.ts"]
+---
+
+# ADR-001: Authentication Engine Selection
+
+## Context & Problem Statement
+ระบบต้องการรองรับทั้ง Email/Password และ OAuth2 SSO (Google, GitHub, Microsoft) สำหรับลูกค้าองค์กร โดยต้องมี Type safety และทำงานร่วมกับ Edge/Node.js runtime ได้
+
+## Decision Drivers
+- Type-safe Client & Server APIs
+- Zero-leak Security Boundary
+- Minimal Third-party Vendor Lock-in
+- Native Support for PostgreSQL + Redis Session Store
+
+## Considered Options
+1. **Option 1**: NextAuth / Auth.js
+2. **Option 2**: Better-Auth
+3. **Option 3**: In-house Custom JWT Implementation
+
+## Decision Outcome
+- **Chosen Option**: **Option 2 (Better-Auth)**
+- **Rationale**: มีโครงสร้างโมดูลที่แยก Layer ชัดเจน (Deep Module), รองรับ TypeScript แบบ 100% strict, และมี built-in rate-limiting รวมถึง CSRF protection
+
+## Consequences & Trade-offs
+### Positive
+- ประหยัดเวลาในการพัฒนา Security middleware
+- Audit ผ่านได้ง่ายเนื่องจากเป็น Open-source ที่ผ่านการทดสอบ
+### Negative
+- ทีมต้องเรียนรู้ Plugin API ของเฟรมเวิร์กใหม่
+
+## Technical Implementation Rules
+- เก็บ Secrets ทั้งหมดใน Environment Variables (`.env`)
+- ใช้งาน Database Adapter ผ่าน Drizzle ORM
+- ห้าม Bypass Session verification middleware เด็ดขาด

package/template/devflow/docs/examples/living-spec/current-feature.example.md

@@ -0,0 +1,113 @@
+---
+id: "{running_id}"
+title: "{Work Title}"
+doc_type: "spec"
+stage: "current-feature"
+created: "{YYYY-MM-DD}"
+updated: "{YYYY-MM-DD}"
+owner: "{Owner/AI}"
+status: "in-progress"
+artifact_language: "th"
+related_run: "{running_id}"
+source_discovery: "{DISC-ID or null}"
+source_idea: "{IDEA-ID or null}"
+dependencies: []
+related_files: []
+---
+
+# Feature: {Work Title}
+
+## 🎯 1. Define & Boundaries
+
+### Problem Statement
+- คำอธิบายปัญหาหรือความต้องการทางธุรกิจที่ชัดเจน
+
+### Proposed Solution
+- สรุปแนวทางแก้ไขเชิงสถาปัตยกรรมและเทคโนโลยีที่ใช้
+
+### In-Scope & Boundaries
+- [x] ขอบเขตที่ต้องส่งมอบในงานนี้ (In-scope item 1)
+- [x] ขอบเขตที่ต้องส่งมอบในงานนี้ (In-scope item 2)
+
+### Non-Goals (Out of Scope)
+- สิ่งที่ไม่ทำในงานนี้ (Out-of-scope item 1)
+- สิ่งที่จะยกยอดไปรอบถัดไป (Deferred item 2)
+
+### Invariants (สิ่งที่ห้ามพังเด็ดขาด)
+- ระบบเดิมส่วนไหนที่ต้องทำงานได้ตามปกติ 100%
+
+---
+
+## 📐 2. Technical Spec & Contracts
+
+### Architecture & Data Contracts
+```typescript
+export interface ExampleDataContract {
+  id: string;
+  name: string;
+  status: 'active' | 'inactive';
+  createdAt: string;
+}
+```
+
+### Acceptance Criteria (AC)
+- [ ] **AC-1**: เงื่อนไขความสำเร็จข้อที่ 1 (สามารถตรวจสอบและทดสอบได้)
+- [ ] **AC-2**: เงื่อนไขความสำเร็จข้อที่ 2 (ครอบคลุม Error handling / Edge cases)
+- [ ] **AC-3**: การผสานรวมและการทำงานร่วมกับส่วนอื่นไม่มีการเกิด Regression
+
+---
+
+## 📋 3. Execution Plan & TDD Checklist
+
+- [ ] **Task 1: Setup & Domain Model**
+  - [ ] `[TDD-Red]` เขียน Unit test สำหรับทดสอบ Domain Model ที่ยังไม่ผ่าน
+  - [ ] `[TDD-Green]` สร้าง Entity และ Type definitions จน Test ผ่าน
+  - [ ] `[TDD-Refactor]` ปรับโครงสร้างโค้ดให้สะอาดและเป็น Deep Module
+
+- [ ] **Task 2: Core Service Implementation**
+  - [ ] `[TDD-Red]` เขียน Service integration test ดัก edge cases
+  - [ ] `[TDD-Green]` พัฒนา Service logic ขั้นต่ำให้ Test ผ่าน
+  - [ ] `[TDD-Refactor]` เพิ่ม error logging และแยก helper functions
+
+- [ ] **Task 3: Verification & Integration Gate**
+  - [ ] `[TDD-Red]` เขียน End-to-end หรือ Component smoke test
+  - [ ] `[TDD-Green]` เชื่อมต่อ UI/API เข้ากับ Core service
+  - [ ] `[TDD-Refactor]` รัน typecheck, linting และ polish โค้ด
+
+---
+
+## ⚡ 4. Implementation Log & Evidence
+
+### Step 1: {Step Title}
+- **Action**: อธิบายการลงมือเขียนโค้ดและไฟล์ที่แก้ไข
+- **Files Modified**: `src/services/example.ts`, `src/types/example.ts`
+- **Diff Summary**:
+```diff
++ export function processData(input: InputData): Result {
++   return { status: 'success' };
++ }
+```
+
+---
+
+## 🧪 5. Multi-Lane Verification Matrix
+
+| Lane | Command | Result | Evidence / Notes |
+| :--- | :--- | :--- | :--- |
+| **Typecheck** | `npm run typecheck` | `PASS` | 0 errors |
+| **Lint** | `npm run lint` | `PASS` | Clean syntax |
+| **Unit Tests** | `npm test` | `PASS` | 14 tests passing |
+| **Manual Proof** | UI / CLI inspection | `PASS` | Verified in browser / terminal |
+
+---
+
+## 📦 6. Release Digest & Retrospective
+
+### Release Summary
+- สรุปผลงานที่ส่งมอบและคุณค่าที่ได้รับ
+
+### Architectural Decisions
+- ลิงก์ไปยัง ADR ที่เกี่ยวข้อง (เช่น `devflow/decisions/ADR-001.md`)
+
+### Retrospective & Lessons Learned
+- สิ่งที่ทำได้ดีและข้อควรระวังสำหรับงานในอนาคต

package/template/devflow/docs/examples/living-spec/discovery.example.md

@@ -0,0 +1,45 @@
+---
+id: "DISC-20260825-001-user-auth"
+title: "Discovery: Modern Authentication & SSO Integration"
+doc_type: "discovery"
+stage: "discovery"
+created: "2026-08-25"
+updated: "2026-08-25"
+owner: "Lead Architect"
+status: "completed"
+decision: "Proceed"
+selected_route: "Direct"
+related_ideas: ["IDEA-012"]
+related_runs: ["001-user-auth"]
+related_files: []
+---
+
+# Discovery: Modern Authentication & SSO Integration
+
+## 1. Request Summary & Problem Statement
+- **Objective**: สำรวจแนวทางการผสานรวมระบบยืนยันตัวตน (Authentication) ร่วมกับ OAuth2 / SSO สำหรับองค์กร
+- **Context**: ระบบเดิมใช้ Local Basic Auth ซึ่งขาดความปลอดภัยและการบริหารจัดการสิทธิ์แบบรวมศูนย์
+
+## 2. Decision-Blocking Unknowns & Feasibility
+- [x] **Unknown 1**: โครงสร้าง Database Schema รองรับ Multi-tenant OAuth provider หรือไม่?
+  - *Finding*: รองรับได้โดยเพิ่มตาราง `accounts` และ `sessions` แบบ decouple
+- [x] **Unknown 2**: ประสิทธิภาพและการจัดเก็บ Token ใน Redis
+  - *Finding*: ทดสอบ Session cache lookup ใช้เวลาเฉลี่ย < 2ms
+
+## 3. Candidate Architectural Routes
+| Route | Pros | Cons | Verdict |
+| :--- | :--- | :--- | :--- |
+| **Custom OAuth2 Provider** | ควบคุมได้ทั้งหมด 100% | Maintenance สูง, ความเสี่ยง Security | ❌ Reject |
+| **Auth.js / Better-Auth** | มาตรฐานความปลอดภัยสูง, Type-safe, Zero-config DB adapters | ต้อง Migrate Session เดิม | ✅ Recommended |
+
+## 4. Architectural Recommendation & Decisions
+- เลือกใช้ **Better-Auth** ร่วมกับ PostgreSQL และ Redis
+- บันทึกรายละเอียดการตัดสินใจลงใน [ADR-001-auth-architecture.md](file:///d:/Projects/devtools/nexus-devflow/devflow/decisions/ADR-001-auth-architecture.md)
+
+## 5. Delivery Slices & Plan Handoff
+- **Slice 1 (Run 001)**: Core Auth Schema & OAuth2 Providers (`/feature "Core Auth Schema and OAuth2"`)
+- **Slice 2 (Run 002)**: Session Management & Middleware (`/feature "Session Middleware"`)
+
+## 6. Decision & Human Sign-off
+- **Status**: `Proceed`
+- **Next Allowed Command**: `/feature 001-user-auth`

package/template/devflow/docs/examples/living-spec/ideas.example.md

@@ -0,0 +1,22 @@
+# Idea Inbox & AI Feasibility Scoring
+
+Centralized repository for new feature proposals, refactoring ideas, and architectural enhancements.
+
+---
+
+## 🔮 Active Backlog Ideas
+
+| ID | Date | Category | Proposal & Core Value | Feasibility | Effort | Value | Status | Source |
+| :--- | :--- | :--- | :--- | :---: | :---: | :---: | :---: | :--- |
+| `[IDEA-001]` | 2026-08-25 | `Security` | **OAuth2 & SSO Integration**: Enterprise Google/GitHub SSO login | `High` | `Medium` | `High` | `In-Progress` | User Request |
+| `[IDEA-002]` | 2026-08-25 | `Performance` | **Single-Flight Git Caching**: Coalescing Git CLI reads to < 120ms | `High` | `Low` | `High` | `Delivered` | Team Review |
+| `[IDEA-003]` | 2026-08-25 | `UI/UX` | **Multi-Agent Swarm Visualizer**: Live role monitoring dashboard | `Medium` | `Medium` | `High` | `Delivered` | Architecture |
+| `[IDEA-004]` | 2026-08-25 | `Tooling` | **MCP Server Hub**: Native 12 tools for IDE integrations | `High` | `Low` | `Medium` | `Ready` | Backlog |
+
+---
+
+## 💡 How to Capture Ideas
+
+- **Via Slash Command**: `/idea "Implement webhook retry queue with exponential backoff"`
+- **Direct Edit**: Add new rows to the table above.
+- **Convert to Feature**: Run `/feature IDEA-004` to consume an idea directly into a Single Living Spec.

package/template/devflow/docs/governance-rules.md

@@ -0,0 +1,39 @@
+# Governance Rules
+
+Use these rules when changing the Nexus-DevFlow framework itself. Keep them practical. If a change does not need a new public surface, do not create one.
+
+---
+
+## 1. Public Surface Rule
+
+- The public workflow surface consists of the **4-stage Living Spec lifecycle** (`/feature`, `/implement`, `/check`, `/complete`) plus the declared **companion skills** (e.g. `/idea`, `/grill`, `/discovery`, `/devflow`, `/doctor`, `/audit`, `/rollback`).
+- Do not introduce a new public command, alternate workflow track, or renamed companion unless the framework truly needs a new user-facing surface.
+- Internal helpers may exist, but they should stay internal until the framework explicitly promotes them.
+
+Example:
+- `/debug` supports root-cause analysis before `/fix` or `/implement`, but it does not replace the delivery lifecycle.
+
+---
+
+## 2. Placement Rules
+
+- **Workflow Stage**: Add or modify a lifecycle stage when the behavior owns a public lifecycle state, required stage artifact, or next-step contract in the active living spec (`devflow/context/{xxx-slug}/spec.md`).
+- **Skill**: Add a skill under `.agents/skills/` and `.claude/skills/` when the behavior is a reusable method that can support multiple workflows or AI agents.
+- **Script**: Add a script under `scripts/` when the change reduces repetition, performs workspace setup, or supports validation without changing the public workflow model.
+- **Validation**: Add validation to `scripts/validate-framework.ts` when the rule is stable, repeated, and important enough that drift should fail fast in CI.
+
+---
+
+## 3. Documentation Placement Rule
+
+- Update `README.md`, `README.th.md`, and `USAGE.md` only when maintainers or users need the change to be discoverable from a high-surface entry point.
+- Put maintainer-operating detail in focused docs under `devflow/docs/` instead of expanding public onboarding pages.
+- Keep `AGENTS.md` aligned with workflow, agent, and skill boundaries, but avoid turning it into a full maintainer manual.
+
+---
+
+## 4. Decision Bias
+
+- Prefer the smallest surface that preserves clarity.
+- Prefer updating an existing doc, skill, script, or validation rule before creating a new one.
+- If two placements seem possible, choose the one that keeps public behavior stable across all supported AI IDEs.

package/template/devflow/docs/manual-review-workflow-spec.md

@@ -0,0 +1,116 @@
+---
+title: Nexus-DevFlow 2.13.0 Manual Review & Quality Gate Specification
+status: active
+updated: 2026-09-07
+owner: Nexus-DevFlow Core Team
+---
+
+# Nexus-DevFlow 2.13.0 Manual Review & Quality Gate Specification
+
+## 1. Purpose & Overview
+
+This specification defines the **Manual Review, Verification Gates, and Audit Discipline** for **Nexus-DevFlow 2.13.0 (The 3-Pillars & Pure Task-Isolated Living Spec Model)**.
+
+In production-grade software development, AI coding assistants should not blindly write code without human alignment. Nexus-DevFlow treats human review as **explicit, non-bypassable gates** throughout the 4-stage delivery lifecycle:
+
+```text
+/feature (or /fix) ──▶ [Spec Gate] ──▶ /implement ──▶ [TDD Checkpoint] ──▶ /check ──▶ [QA Gate] ──▶ /complete ──▶ [Delivery Gate]
+```
+
+---
+
+## 2. The 4 Essential Human Review Gates
+
+### 🚪 Gate 1: The Spec Review Gate (`/feature` / `/fix`)
+- **When**: Triggered immediately after the AI creates or updates `devflow/context/{xxx-slug}/spec.md`.
+- **AI Action**: Defines problem statement, boundaries, data contracts, acceptance criteria (AC-1..AC-N), and TDD execution plan, then **pauses**.
+- **Human Verification Checklist**:
+  1. Are scope boundaries and non-goals explicitly defined?
+  2. Are invariants (what must not break) protected?
+  3. Are acceptance criteria testable and unambiguous?
+  4. Is the TDD execution plan granular (`[TDD-Red]`, `[TDD-Green]`, `[TDD-Refactor]`)?
+- **Approval Rule**: AI does not write application code until the developer reviews and approves the spec.
+
+---
+
+### 🚪 Gate 2: The TDD Implementation Checkpoint (`/implement`)
+- **When**: During task execution in `devflow/context/{xxx-slug}/spec.md`.
+- **AI Action**: Implements tasks one by one under strict Red-Green-Refactor discipline, recording diffs and test logs into the implementation checklist and evidence sections.
+- **Human Verification Checklist**:
+  1. Did each behavior change start with a failing test (`[TDD-Red]`)?
+  2. Is the code diff minimal, clean, and adhering to `coding-standards.md`?
+  3. Were refactoring steps performed without changing public contracts?
+- **Approval Rule**: Optional commit checkpoints on the feature branch after each passing step.
+
+---
+
+### 🚪 Gate 3: Senior QA Verification Gate (`/check`)
+- **When**: After all implementation tasks in the living spec are checked off.
+- **AI Action**: Assumes the role of an independent Senior QA engineer, running the multi-lane verification matrix (Typecheck, Lint, Test suites, and behavioral manual proof).
+- **Human Verification Checklist**:
+  1. Did all lanes in the matrix achieve `PASS`?
+  2. Are test assertions testing behavior rather than mock implementation details?
+  3. Has manual behavioral proof (browser/terminal/API) been recorded?
+- **Approval Rule**: Passing checks recorded as empirical evidence in `devflow/context/{xxx-slug}/spec.md` and any findings logged in `findings.md`.
+
+---
+
+### 🚪 Gate 4: The Findings & Git Delivery Gate (`/audit` + `/complete`)
+- **When**: Final step before closing the work item.
+- **AI Action**:
+  - `/audit current` inspects the complete feature branch delta and records findings in `devflow/context/{xxx-slug}/findings.md`.
+  - `/complete` compiles the Release Digest, updates `HISTORY.md` and `build-plan.md`, archives the living spec to `devflow/history/features/`, cleanly tears down the active task directory, and asks for approval before merging.
+- **Human Verification Checklist**:
+  1. Are all P0 (Critical) and P1 (High) findings in `findings.md` resolved and verified (`closed`) or explicitly waived (`accepted`)?
+  2. Is the Release Digest accurate and complete?
+- **Approval Rule**: Mandatory human confirmation before squash-merging the feature branch into `main` and deleting the branch.
+
+---
+
+## 3. Artifact Placement & State Contracts (The 3-Pillars)
+
+```text
+devflow/
+├── ideas.md                    # 🔮 Future (Backlog): Idea Inbox with AI scoring
+├── project-plan.md             # 🔮 Future (Backlog): Product Vision & Architectural Roadmap
+├── build-plan.md               # 🔮 Future (Backlog): Master Feature Delivery Sequence
+├── context/                    # ⚡ Present (Active Context): Global Truth & Task Workspaces
+│   ├── project-overview.md     # Single Source of Truth
+│   ├── coding-standards.md     # Engineering standards & conventions
+│   ├── ai-interaction.md       # AI interaction guidelines
+│   ├── glossary.md             # Domain glossary & architecture terms
+│   └── {xxx-slug}/             # Active Task-Isolated Workspace
+│       ├── spec.md             # Living Spec & Task Breakdown
+│       ├── stage.md            # Stage pointer & status
+│       └── findings.md         # Dedicated audit & quality ledger
+├── decisions/                  # 🏛️ Decisions: Architecture Decision Records (ADR-xxx.md)
+├── history/                    # 📦 Past (History Archive): Categorized delivery archives
+│   ├── features/               # Shipped features ({xxx-slug}.md)
+│   ├── fixes/                  # Resolved bug fixes ({xxx-slug}.md)
+│   ├── rollbacks/              # Reversal audit logs (YYYY-MM-DD-{xxx-slug}.md)
+│   └── HISTORY.md              # Master release ledger
+└── discoveries/                # 🔍 Discoveries: Pre-delivery discovery records (DISC-xxx.md)
+```
+
+---
+
+## 4. Task-Isolated Living Spec Contract (`spec.md`)
+
+Every delivery run operates on `devflow/context/{xxx-slug}/spec.md`, structured into **6 standard sections**:
+
+1. **🎯 1. Define & Boundaries**: Problem statement, proposed solution, scope boundaries, and non-breaking invariants.
+2. **📐 2. Technical Spec & Contracts**: Data contracts, API schemas, and testable Acceptance Criteria (AC-1..AC-N).
+3. **📋 3. Execution Plan & TDD Checklist**: Sequential task breakdown with granular `[TDD-Red]`, `[TDD-Green]`, and `[TDD-Refactor]` sub-tasks.
+4. **⚡ 4. Implementation Log & Evidence**: Live engineering log recording step-by-step implementation evidence and diffs.
+5. **🧪 5. Multi-Lane Verification Matrix**: Empirical test logs, benchmark data, and manual proof verification.
+6. **📦 6. Release Digest & Retrospective**: Release summary, key architectural decisions, and retrospective notes.
+
+---
+
+## 5. Reference Examples
+
+For complete markdown templates and living spec examples, refer to:
+- [`devflow/docs/examples/living-spec/current-feature.example.md`](examples/living-spec/current-feature.example.md)
+- [`devflow/docs/examples/living-spec/discovery.example.md`](examples/living-spec/discovery.example.md)
+- [`devflow/docs/examples/living-spec/adr.example.md`](examples/living-spec/adr.example.md)
+- [`devflow/docs/examples/living-spec/ideas.example.md`](examples/living-spec/ideas.example.md)

package/template/devflow/docs/markdown-metadata-contract.md

@@ -0,0 +1,140 @@
+# Markdown Metadata Contract
+
+This contract defines the default metadata and heading-tag standard for every Markdown file generated by Nexus-DevFlow agents, workflows, and templates.
+
+The goal is to keep Markdown useful in three places simultaneously:
+1. Human reading in GitHub, code editors, and PR reviews.
+2. Obsidian vault navigation, graph search, and Dataview-style querying.
+3. Agent and script indexing without forcing every report type into an unnatural shape.
+
+---
+
+## 1. Core Rule
+
+Every generated `.md` file should use a hybrid metadata model:
+1. A shared **YAML frontmatter core** at the top of the file.
+2. Optional **type-specific frontmatter fields** based on `doc_type` and `category`.
+3. **Obsidian-compatible heading tags** at the end of headings for section-level semantic meaning.
+
+---
+
+## 2. Required Frontmatter Core
+
+```yaml
+---
+id: "md-YYYY-MM-DD-slug"
+title: "Human-readable title"
+doc_type: "report"
+category: "general"
+status: "draft"
+created: "YYYY-MM-DD"
+updated: "YYYY-MM-DD"
+owner: "agent-or-human"
+source_workflow: null
+related_task: null
+related_files: []
+tags:
+  - nexus-devflow
+aliases: []
+summary: "One or two sentence summary."
+metadata_version: 1
+---
+```
+
+### Required Field Meanings:
+
+| Field | Type | Meaning |
+| :--- | :--- | :--- |
+| `id` | string | Stable unique identifier for this document (e.g. `001-user-auth`, `DISC-20260825-001`, `ADR-001`). |
+| `title` | string | Human-readable document title matching or mirroring H1. |
+| `doc_type` | string | Broad document kind (`spec`, `plan`, `discovery`, `decision`, `report`, `guide`, `changelog`). |
+| `category` | string | Workflow category (`planning`, `qa`, `security`, `release`, `architecture`). |
+| `status` | string | Lifecycle state (`draft`, `in-progress`, `completed`, `accepted`, `archived`). |
+| `created` | string | Creation date in `YYYY-MM-DD` format. |
+| `updated` | string | Last update date in `YYYY-MM-DD` format. |
+| `owner` | string | Responsible agent role or human developer. |
+| `source_workflow` | string \| null | Command that produced the document (e.g. `/feature`, `/audit`, `/grill`). |
+| `related_task` | string \| null | Task ID, issue ID, or PR ID. |
+| `related_files` | string[] | Array of repository paths described or affected. |
+| `tags` | string[] | Obsidian tags without `#`. |
+| `aliases` | string[] | Alternative note aliases. |
+| `summary` | string | Short summary for search and index tables. |
+| `metadata_version`| number | Contract version (`1`). |
+
+---
+
+## 3. Optional Frontmatter By Document Type
+
+### A. Living Spec (`current-feature.md`)
+```yaml
+doc_type: "spec"
+category: "planning"
+stage: "current-feature"
+source_discovery: "DISC-20260825-001"
+source_idea: "IDEA-001"
+```
+
+### B. Pre-Flight Discovery (`discovery.md`)
+```yaml
+doc_type: "discovery"
+category: "architecture"
+decision: "Proceed"
+selected_route: "Direct"
+related_ideas: ["IDEA-001"]
+```
+
+### C. Architecture Decision Record (`ADR-xxx.md`)
+```yaml
+doc_type: "decision"
+category: "architecture"
+status: "accepted"
+deciders: ["Lead Architect", "Security Auditor"]
+```
+
+### D. QA Verification & Audit Report
+```yaml
+doc_type: "report"
+category: "qa"
+qa_result: "pass"
+risk_level: "low"
+finding_count: 0
+```
+
+---
+
+## 4. Heading Tag Contract
+
+Heading tags describe section semantics in Markdown body text (placed at the end of heading lines):
+
+```markdown
+# Living Spec: User Authentication #doc/spec
+
+## 🎯 1. Define & Boundaries #section/scope
+
+## 📐 2. Technical Spec & Contracts #section/contracts
+
+## 📋 3. Execution Plan & TDD Checklist #section/tasks
+
+## ⚡ 4. Implementation Log & Evidence #section/evidence
+
+## 🧪 5. Multi-Lane Verification Matrix #section/verification
+
+## 📦 6. Release Digest & Retrospective #section/summary
+```
+
+### Standard Section Tags:
+- `#section/summary`, `#section/scope`, `#section/contracts`, `#section/tasks`
+- `#section/evidence`, `#section/verification`, `#section/findings`
+- `#finding/bug`, `#finding/security`, `#finding/performance`, `#finding/gap`
+- `#priority/critical`, `#priority/high`, `#priority/medium`, `#priority/low`
+
+---
+
+## 5. Agent Authoring Checklist
+
+Before creating or updating any generated Markdown file:
+- [x] Include the required YAML frontmatter core at the top.
+- [x] Use appropriate `doc_type` and `category`.
+- [x] Ensure tags in frontmatter do not include `#`, while heading tags do include `#`.
+- [x] Keep `updated` timestamp synchronized upon edits.
+- [x] Use relative Markdown file links for cross-document navigation.