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

monoco/features/issue/models.py

@@ -78,16 +78,16 @@ 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[IssueStatus] = None
-    target_stage: Optional[IssueStage] = None
-    target_solution: Optional[IssueSolution] = None
+    target_status: Optional[str] = None
+    target_stage: Optional[str] = None
+    target_solution: Optional[str] = None
     icon: Optional[str] = None
     
     # Generic execution extensions
@@ -99,9 +99,9 @@ class IssueMetadata(BaseModel):
     
     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
@@ -112,21 +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)
-    actions: List[IssueAction] = Field(default=[], exclude=True)
+    # 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()

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

@@ -8,8 +8,13 @@ System for managing tasks using `monoco issue`.
 - **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

@@ -23,6 +23,24 @@ Use this skill to create and manage **Issues** (Universal Atoms) in Monoco proje
 - **🧹 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
@@ -45,7 +63,6 @@ Issues are validated via `monoco issue lint`. key constraints:
 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>`
@@ -56,7 +73,8 @@ Use `monoco issue`:
 
 5. **Modification**: `monoco issue start/submit/delete <id>`
 
-6. **Commit**: `monoco issue commit` (Atomic commit for issue files)
+6. **Sync**: `monoco issue sync-files [id]` (Sync code changes to Issue file)
+
 7. **Validation**: `monoco issue lint` (Enforces compliance)
 
 ## Validation Rules (FEAT-0082)
@@ -85,3 +103,9 @@ 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

@@ -8,8 +8,13 @@
 - **状态**: `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

@@ -38,7 +38,7 @@ Monoco 不仅仅复刻 Jira，而是基于 **"思维模式 (Mindset)"** 重新
 - **Focus**: "How" (为了支撑系统运转，必须做什么)。
 - **Prefix**: `CHORE-`
 
-> 注：取代了传统的 Task 概念。
+> 注: 取代了传统的 Task 概念。
 
 #### 🐞 FIX (修复)
 
@@ -47,7 +47,7 @@ Monoco 不仅仅复刻 Jira，而是基于 **"思维模式 (Mindset)"** 重新
 - **Focus**: "Fix" (恢复原状)。
 - **Prefix**: `FIX-`
 
-> 注：取代了传统的 Bug 概念。
+> 注: 取代了传统的 Bug 概念。
 
 ---
 
@@ -57,6 +57,24 @@ Monoco 不仅仅复刻 Jira，而是基于 **"思维模式 (Mindset)"** 重新
 - **次要**: `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)
 
 ### 目录结构
@@ -68,10 +86,9 @@ Monoco 不仅仅复刻 Jira，而是基于 **"思维模式 (Mindset)"** 重新
 
 ### 路径流转
 
-使用 `monoco issue`：
+使用 `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>`
@@ -82,18 +99,19 @@ Monoco 不仅仅复刻 Jira，而是基于 **"思维模式 (Mindset)"** 重新
 
 5. **Modification**: `monoco issue start/submit/delete <id>`
 
-6. **Commit**: `monoco issue commit` (原子化提交 Issue 文件)
+6. **Sync**: `monoco issue sync-files [id]` (同步代码变更到 Issue 文件)
+
 7. **Validation**: `monoco issue lint` (强制执行合规性检查)
 
 ## 合规与结构校验 (Validation Rules)
 
-为了确保数据严谨性，所有 Issue Ticket 必须遵循以下强制规则：
+为了确保数据严谨性，所有 Issue Ticket 必须遵循以下强制规则:
 
 ### 1. 结构一致性 (Structural Consistency)
 
 - 必须包含一个二级标题 (`##`)，内容必须与 Front Matter 中的 ID 和 Title 严格匹配。
-- 格式：`## {ID}: {Title}`
-- 示例：`## FEAT-0082: Issue Ticket Validator`
+- 格式: `## {ID}: {Title}`
+- 示例: `## FEAT-0082: Issue Ticket Validator`
 
 ### 2. 内容完整性 (Content Completeness)
 
@@ -103,12 +121,18 @@ Monoco 不仅仅复刻 Jira，而是基于 **"思维模式 (Mindset)"** 重新
 ### 3. Checkbox 语法与层级 (Checkbox Matrix)
 
 - 仅限使用: `- [ ]`, `- [x]`, `- [-]`, `- [/]`。
-- **层级继承**: 若存在嵌套 Checkbox，父项状态必须正确反映子项的聚合结果（例如：任一子项为 `[/]` 则父项必为 `[/]`；子项全选则父项为 `[x]`）。
+- **层级继承**: 若存在嵌套 Checkbox，父项状态必须正确反映子项的聚合结果（例如: 任一子项为 `[/]` 则父项必为 `[/]`；子项全选则父项为 `[x]`）。
 
 ### 4. 状态矩阵 (State Matrix)
 
-`status` (物理存放目录) 与 `stage` (Front Matter 字段) 必须兼容：
+`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 将失败并阻止操作。