monoco-toolkit 0.1.1__py3-none-any.whl → 0.2.8__py3-none-any.whl

monoco/features/issue/migration.py

@@ -0,0 +1,134 @@
+import os
+import re
+import yaml
+import hashlib
+import secrets
+from pathlib import Path
+from typing import List, Dict, Any
+from datetime import datetime
+from .models import generate_uid
+
+# Migration Mappings
+DIR_MAP = {
+    "STORIES": "Features",
+    "Stories": "Features",
+    "TASKS": "Chores",
+    "Tasks": "Chores",
+    "BUGS": "Fixes",
+    "Bugs": "Fixes",
+    "EPICS": "Epics",
+    "Epics": "Epics",
+    "features": "Features",
+    "chores": "Chores",
+    "fixes": "Fixes",
+    "epics": "Epics"
+}
+
+TYPE_MAP = {
+    "story": "feature",
+    "task": "chore",
+    "bug": "fix"
+}
+
+ID_PREFIX_MAP = {
+    "STORY": "FEAT",
+    "TASK": "CHORE",
+    "BUG": "FIX"
+}
+
+def migrate_issues_directory(issues_dir: Path):
+    """
+    Core migration logic to upgrade an Issues directory to the latest Monoco standard.
+    """
+    if not issues_dir.exists():
+        return
+
+    # 1. Rename Directories
+    for old_name, new_name in DIR_MAP.items():
+        old_path = issues_dir / old_name
+        if old_path.exists():
+            new_path = issues_dir / new_name
+            
+            # Case sensitivity check for some filesystems
+            same_inode = False
+            try:
+                if new_path.exists() and os.path.samefile(old_path, new_path):
+                    same_inode = True
+            except OSError:
+                pass
+
+            if same_inode:
+                if old_path.name != new_path.name:
+                    old_path.rename(new_path)
+                continue
+
+            if new_path.exists():
+                import shutil
+                for item in old_path.iterdir():
+                    dest = new_path / item.name
+                    if dest.exists() and item.is_dir():
+                        for subitem in item.iterdir():
+                            shutil.move(str(subitem), str(dest / subitem.name))
+                        shutil.rmtree(item)
+                    else:
+                        shutil.move(str(item), str(dest))
+                shutil.rmtree(old_path)
+            else:
+                old_path.rename(new_path)
+
+    # 2. Rename Files and Update Content
+    for subdir_name in ["Features", "Chores", "Fixes", "Epics"]:
+        subdir = issues_dir / subdir_name
+        if not subdir.exists():
+            continue
+            
+        for file_path in subdir.rglob("*.md"):
+            content = file_path.read_text(encoding="utf-8")
+            new_content = content
+            
+            # Replace Type in Frontmatter
+            for old_type, new_type in TYPE_MAP.items():
+                new_content = re.sub(rf"^type:\s*{old_type}", f"type: {new_type}", new_content, flags=re.IGNORECASE | re.MULTILINE)
+            
+            # Replace ID Prefixes
+            for old_prefix, new_prefix in ID_PREFIX_MAP.items():
+                new_content = new_content.replace(f"[[{old_prefix}-", f"[[{new_prefix}-")
+                new_content = re.sub(rf"^id: {old_prefix}-", f"id: {new_prefix}-", new_content, flags=re.MULTILINE)
+                new_content = re.sub(rf"^parent: {old_prefix}-", f"parent: {new_prefix}-", new_content, flags=re.MULTILINE)
+                new_content = new_content.replace(f"{old_prefix}-", f"{new_prefix}-")
+
+            # Structural Updates (UID, Stage)
+            match = re.search(r"^---(.*?)---", new_content, re.DOTALL | re.MULTILINE)
+            if match:
+                yaml_str = match.group(1)
+                try:
+                    data = yaml.safe_load(yaml_str) or {}
+                    changed = False
+                    
+                    if 'uid' not in data:
+                        data['uid'] = generate_uid()
+                        changed = True
+                        
+                    if 'stage' in data and data['stage'] == 'todo':
+                        data['stage'] = 'draft'
+                        changed = True
+                            
+                    if changed:
+                         new_yaml = yaml.dump(data, sort_keys=False, allow_unicode=True)
+                         new_content = new_content.replace(match.group(1), "\n" + new_yaml)
+                except yaml.YAMLError:
+                    pass
+
+            if new_content != content:
+                file_path.write_text(new_content, encoding="utf-8")
+
+            # Rename File
+            filename = file_path.name
+            new_filename = filename
+            for old_prefix, new_prefix in ID_PREFIX_MAP.items():
+                if filename.startswith(f"{old_prefix}-"):
+                    new_filename = filename.replace(f"{old_prefix}-", f"{new_prefix}-", 1)
+                    break
+            
+            if new_filename != filename:
+                file_path.rename(file_path.parent / new_filename)

monoco/features/issue/models.py

@@ -1,5 +1,5 @@
 from enum import Enum
-from typing import List, Optional, Any
+from typing import List, Optional, Any, Dict
 from pydantic import BaseModel, Field, model_validator
 from datetime import datetime
 import hashlib
@@ -61,7 +61,7 @@ class IssueStatus(str, Enum):
     BACKLOG = "backlog"
 
 class IssueStage(str, Enum):
-    TODO = "todo"
+    DRAFT = "draft"
     DOING = "doing"
     REVIEW = "review"
     DONE = "done"
@@ -78,19 +78,30 @@ class IsolationType(str, Enum):
     WORKTREE = "worktree"
 
 class IssueIsolation(BaseModel):
-    type: IsolationType
+    type: str
     ref: str  # Git branch name
     path: Optional[str] = None  # Worktree path (relative to repo root or absolute)
     created_at: datetime = Field(default_factory=current_time)
 
+class IssueAction(BaseModel):
+    label: str
+    target_status: Optional[str] = None
+    target_stage: Optional[str] = None
+    target_solution: Optional[str] = None
+    icon: Optional[str] = None
+    
+    # Generic execution extensions
+    command: Optional[str] = None
+    params: Dict[str, Any] = {}
+
 class IssueMetadata(BaseModel):
     model_config = {"extra": "allow"}
     
     id: str
     uid: Optional[str] = None  # Global unique identifier for cross-project identity
-    type: IssueType
-    status: IssueStatus = IssueStatus.OPEN
-    stage: Optional[IssueStage] = None
+    type: str
+    status: str = "open"
+    stage: Optional[str] = None
     title: str
     
     # Time Anchors
@@ -101,17 +112,39 @@ class IssueMetadata(BaseModel):
 
     parent: Optional[str] = None
     sprint: Optional[str] = None
-    solution: Optional[IssueSolution] = None
+    solution: Optional[str] = None
     isolation: Optional[IssueIsolation] = None
     dependencies: List[str] = []
     related: List[str] = []
     tags: List[str] = []
+    files: List[str] = []
+    path: Optional[str] = None  # Absolute path to the issue file
+    
+    # Proxy UI Actions (Excluded from file persistence)
+    # Modified: Remove exclude=True to allow API/CLI inspection. Must be manually excluded during YAML Dump.
+    actions: List[IssueAction] = Field(default=[])
 
 
     @model_validator(mode='before')
     @classmethod
     def normalize_fields(cls, v: Any) -> Any:
         if isinstance(v, dict):
+            # Handle common capitalization variations for robustness
+            field_map = {
+                "ID": "id",
+                "Type": "type",
+                "Status": "status",
+                "Stage": "stage",
+                "Title": "title",
+                "Parent": "parent",
+                "Solution": "solution",
+                "Sprint": "sprint",
+            }
+            for old_k, new_k in field_map.items():
+                if old_k in v and new_k not in v:
+                    v[new_k] = v[old_k] # Don't pop yet to avoid mutation issues if used elsewhere, or pop if safe.
+                    # Pydantic v2 mode='before' is usually a copy if we want to be safe, but let's just add it.
+
             # Normalize type and status to lowercase for compatibility
             if "type" in v and isinstance(v["type"], str):
                 v["type"] = v["type"].lower()
@@ -122,30 +155,19 @@ class IssueMetadata(BaseModel):
             # Stage normalization
             if "stage" in v and isinstance(v["stage"], str):
                 v["stage"] = v["stage"].lower()
+                if v["stage"] == "todo":
+                    v["stage"] = "draft"
         return v
 
     @model_validator(mode='after')
     def validate_lifecycle(self) -> 'IssueMetadata':
         # Logic Definition:
-        # status: backlog -> stage: null
+        # status: backlog -> stage: freezed
         # status: closed -> stage: done
-        # status: open -> stage: todo | doing | review (default todo)
-
-        if self.status == IssueStatus.BACKLOG:
-            self.stage = IssueStage.FREEZED
-        
-        elif self.status == IssueStatus.CLOSED:
-            # Enforce stage=done for closed issues
-            if self.stage != IssueStage.DONE:
-                self.stage = IssueStage.DONE
-            # Auto-fill closed_at if missing
-            if not self.closed_at:
-                self.closed_at = current_time()
+        # status: open -> stage: draft | doing | review | done (default draft)
         
-        elif self.status == IssueStatus.OPEN:
-            # Ensure valid stage for open status
-            if self.stage is None or self.stage == IssueStage.DONE:
-                self.stage = IssueStage.TODO
+        # NOTE: We do NOT auto-correct state here anymore to allow Linter to detect inconsistencies.
+        # Auto-correction should be applied explicitly by 'create' or 'update' commands via core logic.
         
         return self
 

monoco/features/issue/monitor.py

@@ -0,0 +1,94 @@
+import re
+import asyncio
+import logging
+from pathlib import Path
+from typing import Callable, Awaitable, Any, Optional
+
+from watchdog.observers import Observer
+from watchdog.events import FileSystemEventHandler
+
+logger = logging.getLogger("monoco.features.issue.monitor")
+
+class IssueEventHandler(FileSystemEventHandler):
+    def __init__(self, loop, on_upsert: Callable[[dict], Awaitable[None]], on_delete: Callable[[dict], Awaitable[None]]):
+        self.loop = loop
+        self.on_upsert = on_upsert
+        self.on_delete = on_delete
+
+    def _process_upsert(self, path_str: str):
+        if not path_str.endswith(".md"):
+            return
+        asyncio.run_coroutine_threadsafe(self._handle_upsert(path_str), self.loop)
+    
+    async def _handle_upsert(self, path_str: str):
+        try:
+            from monoco.features.issue.core import parse_issue
+            path = Path(path_str)
+            if not path.exists():
+                return
+            issue = parse_issue(path)
+            if issue:
+                await self.on_upsert(issue.model_dump(mode='json'))
+        except Exception as e:
+            logger.error(f"Error handling upsert for {path_str}: {e}")
+
+    def _process_delete(self, path_str: str):
+        if not path_str.endswith(".md"):
+            return
+        asyncio.run_coroutine_threadsafe(self._handle_delete(path_str), self.loop)
+
+    async def _handle_delete(self, path_str: str):
+        try:
+            filename = Path(path_str).name
+            match = re.match(r"([A-Z]+-\d{4})", filename)
+            if match:
+                issue_id = match.group(1)
+                await self.on_delete({"id": issue_id})
+        except Exception as e:
+            logger.error(f"Error handling delete for {path_str}: {e}")
+
+    def on_created(self, event):
+        if not event.is_directory:
+            self._process_upsert(event.src_path)
+
+    def on_modified(self, event):
+        if not event.is_directory:
+            self._process_upsert(event.src_path)
+            
+    def on_deleted(self, event):
+        if not event.is_directory:
+            self._process_delete(event.src_path)
+
+    def on_moved(self, event):
+        if not event.is_directory:
+            self._process_delete(event.src_path)
+            self._process_upsert(event.dest_path)
+
+class IssueMonitor:
+    """
+    Monitor the Issues directory for changes using Watchdog and trigger callbacks.
+    """
+    def __init__(self, issues_root: Path, on_upsert: Callable[[dict], Awaitable[None]], on_delete: Callable[[dict], Awaitable[None]]):
+        self.issues_root = issues_root
+        self.on_upsert = on_upsert
+        self.on_delete = on_delete
+        self.observer = Observer()
+        self.loop = None
+
+    async def start(self):
+        self.loop = asyncio.get_running_loop()
+        event_handler = IssueEventHandler(self.loop, self.on_upsert, self.on_delete)
+        
+        if not self.issues_root.exists():
+            logger.warning(f"Issues root {self.issues_root} does not exist. creating...")
+            self.issues_root.mkdir(parents=True, exist_ok=True)
+
+        self.observer.schedule(event_handler, str(self.issues_root), recursive=True)
+        self.observer.start()
+        logger.info(f"Issue Monitor started (Watchdog). Watching {self.issues_root}")
+
+    def stop(self):
+        if self.observer.is_alive():
+            self.observer.stop()
+            self.observer.join()
+        logger.info(f"Issue Monitor stopped for {self.issues_root}")

monoco/features/issue/resources/en/AGENTS.md

@@ -0,0 +1,20 @@
+# Issue Management (Agent Guidance)
+
+## Issue Management
+
+System for managing tasks using `monoco issue`.
+
+- **Create**: `monoco issue create <type> -t "Title"` (types: epic, feature, chore, fix)
+- **Status**: `monoco issue open|close|backlog <id>`
+- **Check**: `monoco issue lint` (Must run after manual edits)
+- **Lifecycle**: `monoco issue start|submit|delete <id>`
+- **Sync Context**: `monoco issue sync-files [id]` (Update file tracking)
+- **Structure**: `Issues/{CapitalizedPluralType}/{lowercase_status}/` (e.g. `Issues/Features/open/`). Do not deviate.
+- **Rules**:
+  1. **Heading**: Must have `## {ID}: {Title}` (matches metadata).
+  2. **Checkboxes**: Min 2 using `- [ ]`, `- [x]`, `- [-]`, `- [/]`.
+  3. **Review**: `## Review Comments` section required for Review/Done stages.
+  4. **Environment Policies**:
+     - Must use `monoco issue start --branch`.
+     - 🛑 **NO** direct coding on `main`/`master` (Linter will fail).
+     - Must update `files` field after coding (via `sync-files` or manual).

monoco/features/issue/resources/en/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: monoco-issue
+description: Official skill for Monoco Issue System. Treats Issues as Universal Atoms, managing the lifecycle of Epic/Feature/Chore/Fix.
+---
+
+# Issue Management
+
+Use this skill to create and manage **Issues** (Universal Atoms) in Monoco projects.
+
+## Core Ontology
+
+### 1. Strategy Layer
+
+- **🏆 EPIC**: Grand goals, vision containers. Mindset: Architect.
+
+### 2. Value Layer
+
+- **✨ FEATURE**: Value increments from user perspective. Mindset: Product Owner.
+- **Atomicity Principle**: Feature = Design + Dev + Test + Doc + i18n. They are one.
+
+### 3. Execution Layer
+
+- **🧹 CHORE**: Engineering maintenance, no direct user value. Mindset: Builder.
+- **🐞 FIX**: Correcting deviations. Mindset: Debugger.
+
+## Workflow Policies
+
+### 1. Strict Git Workflow
+
+Monoco enforces a **Feature Branch** model.
+
+- **Start**: Must use `monoco issue start <ID> --branch` to start working. This creates a `feat/<ID>-<slug>` branch.
+- **Protected Main**: **NO** direct modification on `main`, `master`, or `production` branches. Linter will block this.
+- **Submit**: Run `monoco issue submit <ID>` before PR to clean up and validate.
+
+### 2. File Tracking
+
+Agents must track modified files to maintain Self-Contained Context.
+
+- **Mechanism**: Issue Ticket Front Matter contains a `files: []` field.
+- **Automated (Recommended)**: Run `monoco issue sync-files` inside the Feature Branch. It diffs against the base branch.
+- **Manual (Fallback)**: If working without branches, Agent MUST **actively** append modified paths to the `files` list.
+
+## Guidelines
+
+### Directory Structure & Naming
+
+`Issues/{CapitalizedPluralType}/{lowercase_status}/`
+
+- **Types**: `Epics`, `Features`, `Chores`, `Fixes`
+- **Statuses**: `open`, `backlog`, `closed`
+
+### Structural Integrity
+
+Issues are validated via `monoco issue lint`. key constraints:
+
+1. **Mandatory Heading**: `## {ID}: {Title}` must match front matter.
+2. **Min Checkboxes**: At least 2 checkboxes (AC/Tasks).
+3. **Review Protocol**: `## Review Comments` required for `review` or `done` stages.
+
+### Path Transitions
+
+Use `monoco issue`:
+
+1. **Create**: `monoco issue create <type> --title "..."`
+   - Params: `--parent <id>`, `--dependency <id>`, `--related <id>`, `--sprint <id>`, `--tags <tag>`
+
+2. **Transition**: `monoco issue open/close/backlog <id>`
+
+3. **View**: `monoco issue scope`
+
+4. **Validation**: `monoco issue lint`
+
+5. **Modification**: `monoco issue start/submit/delete <id>`
+
+6. **Sync**: `monoco issue sync-files [id]` (Sync code changes to Issue file)
+
+7. **Validation**: `monoco issue lint` (Enforces compliance)
+
+## Validation Rules (FEAT-0082)
+
+To ensure data integrity, all Issue tickets must follow these strict rules:
+
+### 1. Structural Consistency
+
+- Must contain a Level 2 Heading matching exactly: `## {ID}: {Title}`.
+- Example: `## FEAT-0082: Issue Ticket Validator`
+
+### 2. Content Completeness
+
+- **Checkboxes**: Minimum of 2 checkboxes required (one for AC, one for Tasks).
+- **Review Comments**: If `stage` is `review` or `done`, a `## Review Comments` section is mandatory and must not be empty.
+
+### 3. Checkbox Syntax & Hierarchy
+
+- Use only `- [ ]`, `- [x]`, `- [-]`, or `- [/]`.
+- **Inheritance**: If nested checkboxes exist, the parent state must reflect child states (e.g., if any child is `[/]`, parent must be `[/]`; if all children are `[x]`, parent must be `[x]`).
+
+### 4. State Matrix
+
+The `status` (folder) and `stage` (front matter) must be compatible:
+
+- **open**: Draft, Doing, Review, Done
+- **backlog**: Draft, Doing, Review
+- **closed**: Done
+
+### 5. Environment Policy
+
+Linter includes environment-aware guardrails:
+
+- 🛑 **Dirty Main Protection**: Fails if uncommitted changes are detected on protected branches (`main`/`master`).

monoco/features/issue/resources/zh/AGENTS.md

@@ -0,0 +1,20 @@
+# Issue 管理 (Agent 指引)
+
+## Issue 管理
+
+使用 `monoco issue` 管理任务的系统。
+
+- **创建**: `monoco issue create <type> -t "标题"` (类型: epic, feature, chore, fix)
+- **状态**: `monoco issue open|close|backlog <id>`
+- **检查**: `monoco issue lint` (手动编辑后必须运行)
+- **生命周期**: `monoco issue start|submit|delete <id>`
+- **上下文同步**: `monoco issue sync-files [id]` (更新文件追踪)
+- **结构**: `Issues/{CapitalizedPluralType}/{lowercase_status}/` (如 `Issues/Features/open/`)。
+- **强制规则**:
+  1. **标题**: 必须包含 `## {ID}: {Title}` 标题（与 Front Matter 一致）。
+  2. **内容**: 至少 2 个 Checkbox，使用 `- [ ]`, `- [x]`, `- [-]`, `- [/]`。
+  3. **评审**: `review`/`done` 阶段必须包含 `## Review Comments` 章节且内容不为空。
+  4. **环境策略**:
+     - 必须使用 `monoco issue start --branch` 创建 Feature 分支。
+     - 🛑 **禁止**直接在 `main`/`master` 分支修改代码 (Linter 会报错)。
+     - 修改代码后**必须**更新 `files` 字段（通过 `sync-files` 或手动）。

monoco/features/issue/resources/zh/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: monoco-issue
+description: Monoco Issue System 的官方技能定义。将 Issue 视为通用原子 (Universal Atom)，管理 Epic/Feature/Chore/Fix 的生命周期。
+---
+
+# 自我管理 (Monoco Issue System)
+
+使用此技能在 Monoco 项目中创建和管理 **Issue** (通用原子)。该系统参考 Jira 表达体系，同时保持 "建设者 (Builder)" 和 "调试者 (Debugger)" 思维模式的隔离。
+
+## 核心本体论 (Core Ontology)
+
+Monoco 不仅仅复刻 Jira，而是基于 **"思维模式 (Mindset)"** 重新定义工作单元。
+
+### 1. 战略层 (Strategy)
+
+#### 🏆 EPIC (史诗)
+
+- **Mindset**: _Architect_ (架构师)
+- **定义**: 跨越多个周期的宏大目标。它不是单纯的"大任务"，而是"愿景的容器"。
+- **产出**: 定义了系统的边界和核心价值。
+
+### 2. 价值层 (Value)
+
+#### ✨ FEATURE (特性)
+
+- **Mindset**: _Product Owner_ (产品负责人)
+- **定义**: 用户视角的价值增量。必须是可独立交付 (Shippable) 的垂直切片。
+- **Focus**: "Why" & "What" (用户想要什么？)。
+- **Prefix**: `FEAT-`
+
+### 3. 执行层 (Execution)
+
+#### 🧹 CHORE (杂务)
+
+- **Mindset**: _Builder_ (建设者)
+- **定义**: **不产生**直接用户价值的工程性事务。
+- **场景**: 架构升级、写构建脚本、修复 CI/CD 流水线。
+- **Focus**: "How" (为了支撑系统运转，必须做什么)。
+- **Prefix**: `CHORE-`
+
+> 注: 取代了传统的 Task 概念。
+
+#### 🐞 FIX (修复)
+
+- **Mindset**: _Debugger_ (调试者)
+- **定义**: 预期与现实的偏差。它是负价值的修正。
+- **Focus**: "Fix" (恢复原状)。
+- **Prefix**: `FIX-`
+
+> 注: 取代了传统的 Bug 概念。
+
+---
+
+**关系链**:
+
+- **主要**: `EPIC` (愿景) -> `FEATURE` (价值交付单元)
+- **次要**: `CHORE` (工程维护/支撑) - 通常独立存在。
+- **原子性原则**: Feature = Design + Dev + Test + Doc + i18n。它们是一体的。
+
+## 工作流策略 (Workflow Policies)
+
+### 1. 严格 Git 工作流 (Strict Git Workflow)
+
+Monoco 强制采用 **Feature Branch** 模式。
+
+- **Start**: 必须使用 `monoco issue start <ID> --branch` 启动任务。这会自动创建 `feat/<ID>-<slug>` 分支。
+- **禁止主干开发**: **严禁** 直接在 `main`, `master`, `production` 分支上修改代码。Linter 会拦截此类行为。
+- **Submit**: 在提交 PR 前，运行 `monoco issue submit <ID>` 进行清理和预发布检查。
+
+### 2. 文件追踪 (File Tracking)
+
+为了保证上下文的自包含性 (Self-Contained Context)，Agent 必须记录修改过的文件。
+
+- **机制**: Issue Ticket 的 Front Matter 包含 `files: []` 字段。
+- **自动化 (推荐)**: 在 Feature Branch 中运行 `monoco issue sync-files`。它会自动对比当前分支与 Base 分支的差异并更新列表。
+- **手动 (备选)**: 如果进行非分支开发，Agent 必须**主动**将修改的文件路径写入 `files` 列表。
+
+## 准则 (Guidelines)
+
+### 目录结构
+
+`Issues/{CapitalizedPluralType}/{lowercase_status}/`
+
+- `{TYPE}`: `Epics`, `Features`, `Chores`, `Fixes`
+- `{STATUS}`: `open`, `backlog`, `closed`
+
+### 路径流转
+
+使用 `monoco issue`:
+
+1. **Create**: `monoco issue create <type> --title "..."`
+   - Params: `--parent <id>`, `--dependency <id>`, `--related <id>`, `--sprint <id>`, `--tags <tag>`
+
+2. **Transition**: `monoco issue open/close/backlog <id>`
+
+3. **View**: `monoco issue scope`
+
+4. **Validation**: `monoco issue lint`
+
+5. **Modification**: `monoco issue start/submit/delete <id>`
+
+6. **Sync**: `monoco issue sync-files [id]` (同步代码变更到 Issue 文件)
+
+7. **Validation**: `monoco issue lint` (强制执行合规性检查)
+
+## 合规与结构校验 (Validation Rules)
+
+为了确保数据严谨性，所有 Issue Ticket 必须遵循以下强制规则:
+
+### 1. 结构一致性 (Structural Consistency)
+
+- 必须包含一个二级标题 (`##`)，内容必须与 Front Matter 中的 ID 和 Title 严格匹配。
+- 格式: `## {ID}: {Title}`
+- 示例: `## FEAT-0082: Issue Ticket Validator`
+
+### 2. 内容完整性 (Content Completeness)
+
+- **Checkbox 数量**: 每个 Ticket 必须包含至少 2 个 Checkbox（通常代表 AC 和 Tasks）。
+- **评审记录**: 当 `stage` 为 `review` 或 `done` 时，必须包含 `## Review Comments` 标题且内容不能为空。
+
+### 3. Checkbox 语法与层级 (Checkbox Matrix)
+
+- 仅限使用: `- [ ]`, `- [x]`, `- [-]`, `- [/]`。
+- **层级继承**: 若存在嵌套 Checkbox，父项状态必须正确反映子项的聚合结果（例如: 任一子项为 `[/]` 则父项必为 `[/]`；子项全选则父项为 `[x]`）。
+
+### 4. 状态矩阵 (State Matrix)
+
+`status` (物理存放目录) 与 `stage` (Front Matter 字段) 必须兼容:
+
+- **open**: Draft, Doing, Review, Done
+- **backlog**: Draft, Doing, Review
+- **closed**: Done
+
+### 5. 环境策略 (Environment Policy)
+
+Linter 包含环境感知防护：
+
+- 🛑 **Dirty Main Protection**: 当检测到处于受保护分支 (`main`/`master`) 且存在未提交变更时，Lint 将失败并阻止操作。